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>
3.3 KiB
01 — Prerequisites
Everything here targets amd64 (standard 64-bit x86 — a spare PC, mini PC, or an amd64 VM). If your hardware is arm64 (Raspberry Pi, Apple Silicon VM), the tools below all publish arm64 builds too; swap the architecture in whichever install command you use and the rest of this guide is unchanged.
1. A target machine
You need one machine to become your cluster node — a spare physical PC, a mini PC, or a VM (VirtualBox, UTM, Proxmox, or any hypervisor that can boot from an ISO). Minimum realistic spec: 2 CPU cores, 4GB RAM, 20GB disk.
It needs to be reachable over the network from your everyday machine (the
one you'll run talosctl and kubectl from), and it needs a stable IP
address — see the note about DHCP reservations in
talos/README.md.
You do not need to install an OS on it yet. That's what the next doc covers — Talos gets installed by booting a special ISO and sending it configuration over the network, not through a normal installer.
Download the Talos amd64 ISO from the
Talos releases page (look
for metal-amd64.iso under the latest release) and boot your target machine
from it. Leave it sitting at the boot screen — you'll configure it in
docs/02-talos-bootstrap.md.
Ask Claude: if you're not sure whether to use a VM or spare physical hardware, ask — the tradeoffs (snapshots and easy resets vs. more realistic networking) are worth five minutes of discussion before you commit.
2. talosctl
The CLI you use to configure and manage Talos nodes.
macOS (Homebrew):
brew install siderolabs/tap/talosctl
Linux:
curl -sL https://talos.dev/install | sh
Verify:
talosctl version --client
3. kubectl
The standard Kubernetes CLI — you'll use it constantly, for this and every future Kubernetes cluster you touch.
macOS (Homebrew):
brew install kubectl
Linux: follow the official install instructions for your distribution.
Verify:
kubectl version --client
4. argocd CLI
The command-line client for Argo CD — used mainly to log in and inspect Applications; most day-to-day work happens through Git, not this CLI.
macOS (Homebrew):
brew install argocd
Linux:
Download the argocd-linux-amd64 binary from the
Argo CD releases page, then:
chmod +x argocd-linux-amd64
sudo mv argocd-linux-amd64 /usr/local/bin/argocd
Verify:
argocd version --client
5. A GitHub account and a fork of this repo
This whole system works by Argo CD reading a Git repository you control. Fork this repo (or create a new repo from it) on GitHub, and clone your copy — not the original — to work from. Every command later in this guide that references a repo URL means your fork's URL.
Checklist
- Target machine chosen, network-reachable, IP address noted
- Talos ISO downloaded, machine booted from it and idle at the boot screen
talosctl version --clientworkskubectl version --clientworksargocd version --clientworks- You have your own fork of this repo cloned locally
Once all of these are true, continue to
docs/02-talos-bootstrap.md.