k8s-starter-pack/docs/02-talos-bootstrap.md

02 — Bootstrapping Talos

At the end of this doc, you'll have a single-node Kubernetes cluster, running nothing but Kubernetes itself. No Argo CD yet — that's next.

Why Talos, specifically

Most guides have you install a general-purpose Linux distribution, then install Kubernetes on top by hand or with a tool like kubeadm — meaning there's a whole normal OS underneath, with a package manager, an SSH daemon, and every other thing that can drift out of a known-good state or need patching. Talos throws that away: it's an OS whose only job is running Kubernetes. There's no SSH, no shell to log into, no packages to manage — you configure it entirely by sending it a machine config file over the network (the talosctl commands below), and it applies that config the same declarative way Kubernetes applies your app manifests. Less surface area, less to secure, less to keep in sync by hand — the same philosophy as the rest of this stack, one layer lower.

Single node, on purpose

A "real" Kubernetes cluster usually has multiple nodes — some running the control plane (the brain: API server, scheduler, the cluster's database) and others as workers (running your actual apps), so that losing one machine doesn't take the whole cluster down. This repo starts with exactly one node acting as both, because that's the cheapest way to learn the concepts that matter for GitOps without needing multiple machines. docs/08-growing-up.md covers adding more nodes once you're comfortable — the config here is deliberately compatible with that path, not a dead end.

Steps

Full exact commands live in talos/README.md — read that alongside this doc; this section explains what's happening at each stage, that one has copy-paste blocks.

1. Generate machine configuration. talosctl gen config produces Talos's config files for your cluster, including talos/patch-controlplane.yaml — read that file, it's short and explains itself — which lets your one node run workloads as well as the control plane.

2. Apply the config to your node. The node, freshly booted from the Talos ISO, is sitting in "maintenance mode" with no configuration. talosctl apply-config sends it the config generated in step 1. The node reboots, installs Talos to its disk, and comes up running for real.

3. Bootstrap etcd. talosctl bootstrap initializes the cluster's data store. This is a one-time, one-node-ever operation — even in a multi-node cluster you only ever bootstrap once.

4. Retrieve your kubeconfig. talosctl kubeconfig downloads the credentials you'll use to talk to Kubernetes with kubectl — the Kubernetes equivalent of the talosconfig you got in step 1.

5. Verify. kubectl get nodes should show one node, Ready.

Ask Claude: "what's the difference between a kubeconfig and a talosconfig, and why are they separate files?" is a good one to ask once you've got both — the split trips people up the first time.

Checklist

• _out/controlplane.yaml, worker.yaml, and talosconfig generated
• Config applied to the node, node has rebooted and installed Talos
• talosctl bootstrap run exactly once
• kubeconfig retrieved
• kubectl get nodes shows one Ready node

Once your node is Ready, continue to docs/03-installing-argocd.md.