Initial commit: GitOps Starter Pack

A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with
an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on
bare metal, a demo app, and a progressive docs/ walkthrough with a
CLAUDE.md tutor persona and guided bootstrap checklist.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

talos/README.md

@@ -0,0 +1,123 @@
+# Talos bootstrap — command reference
+
+This is the detailed, copy-pasteable companion to
+[`docs/02-talos-bootstrap.md`](../docs/02-talos-bootstrap.md). Read that file
+first for the explanations — this one is here so you have every exact
+command in one place once you understand what they do.
+
+Throughout, replace `<NODE_IP>` with your machine's real IP address. If it's
+a VM, give it a DHCP reservation (a fixed IP tied to its MAC address) in your
+router or hypervisor before you start, so the address never changes under
+the cluster. Talos bakes the IP into certificates during setup, and changing
+it later means starting over.
+
+All commands assume you're running them from the root of this repo.
+
+## 1. Generate machine configuration
+
+```sh
+talosctl gen config gitops-starter https://<NODE_IP>:6443 \
+  --output-dir _out \
+  --config-patch-control-plane @talos/patch-controlplane.yaml
+```
+
+This writes three files into `_out/` (already covered by this repo's
+`.gitignore` — they contain private keys and must never be committed):
+
+- `controlplane.yaml` — the full machine configuration for a control-plane
+  node, with our single-node patch baked in.
+- `worker.yaml` — a worker machine configuration. Unused for now (single
+  node), kept for when you follow docs/08-growing-up.md.
+- `talosconfig` — *your* client credentials for talking to the Talos API on
+  this cluster (equivalent in spirit to a kubeconfig, but for Talos itself
+  rather than Kubernetes).
+
+`gitops-starter` is the cluster name — an arbitrary label baked into the
+generated certificates and config, used to tell clusters apart if you ever
+manage more than one. `https://<NODE_IP>:6443` is the cluster's Kubernetes
+API endpoint: port 6443 is the standard Kubernetes API server port, and this
+same address gets written into the certificates and your future kubeconfig.
+
+## 2. Point talosctl at this cluster
+
+```sh
+export TALOSCONFIG=_out/talosconfig
+talosctl config endpoint <NODE_IP>
+talosctl config node <NODE_IP>
+```
+
+`endpoint` is which machine talosctl *talks to*. `node` is which machine a
+command *applies to*. On a single-node cluster they're the same address, but
+Talos always keeps the two concepts separate, because on a multi-node
+cluster you often want to ask one node about another.
+
+## 3. Apply the configuration
+
+Boot the target machine from the Talos ISO (see
+[docs/01-prerequisites.md](../docs/01-prerequisites.md) for where to get it).
+It boots into "maintenance mode" — alive enough to accept a configuration,
+with nothing installed yet. Confirm it's reachable, then apply:
+
+```sh
+talosctl get disks --insecure --nodes <NODE_IP>
+```
+
+Note the disk name you want Talos installed to (e.g. `/dev/sda`). Then:
+
+```sh
+talosctl apply-config --insecure \
+  --nodes <NODE_IP> \
+  --file _out/controlplane.yaml
+```
+
+`--insecure` is required for this one command only: the node has no
+certificates yet, so talosctl can't authenticate to it normally. This is
+the one moment during setup where you're trusting the network — do this on
+a network you control. The node will reboot, install Talos to disk, and
+come back up running the configuration you gave it — now *with*
+certificates, so every command after this uses the secure path.
+
+## 4. Bootstrap etcd
+
+Talos is installed and Kubernetes components are starting, but the cluster
+has no data store yet. This one-time command initializes it:
+
+```sh
+talosctl bootstrap --nodes <NODE_IP>
+```
+
+Run this exactly once per cluster, against exactly one control-plane node,
+even if you later add more. Running it again on an existing cluster can
+corrupt it.
+
+## 5. Get your kubeconfig
+
+```sh
+talosctl kubeconfig --nodes <NODE_IP> .
+```
+
+Downloads a kubeconfig into the current directory (also gitignored —
+it grants full cluster access). Merge it with `~/.kube/config` or point
+`KUBECONFIG` at it directly:
+
+```sh
+export KUBECONFIG=$PWD/kubeconfig
+```
+
+## 6. Verify
+
+```sh
+kubectl get nodes
+```
+
+Expect to see one node, `Ready`, within a couple of minutes (it takes a
+moment for the default CNI — Talos ships Flannel out of the box — to come
+up and clear the node's networking checks).
+
+```
+NAME              STATUS   ROLES           AGE   VERSION
+talos-...         Ready    control-plane   90s   v1.3x.x
+```
+
+If it's stuck on `NotReady`, give it another minute before troubleshooting —
+first boot does a lot of one-time work.

talos/patch-controlplane.yaml

@@ -0,0 +1,15 @@
+# A patch applied on top of the controlplane.yaml that `talosctl gen config`
+# produces (see talos/README.md and docs/02-talos-bootstrap.md for the full
+# command). Talos's generated defaults assume a multi-node cluster where
+# control-plane nodes only run the Kubernetes control plane itself (API
+# server, scheduler, etcd, etc.) and never your actual workloads. For a
+# single-node learning cluster, that would mean nothing can ever be
+# scheduled — there's no other node to run it on.
+#
+# This one field undoes that restriction, letting the single node be both
+# the control plane AND a worker.
+#
+# >> Ask Claude: "why does Kubernetes normally keep workloads off control
+#    plane nodes?" if you want the reasoning before you turn it off.
+cluster:
+  allowSchedulingOnControlPlanes: true