Maxwell MorrisandClaude Sonnet 5
92c3ad3191
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>
73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
# 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`](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`](../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`](../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`](03-installing-argocd.md).
|