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>
2026-08-22 17:30:45 +01:00
commit 92c3ad3191
29 changed files with 2083 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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`](../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](https://github.com/siderolabs/talos/releases) (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`](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):**
+```sh
+brew install siderolabs/tap/talosctl
+```
+
+**Linux:**
+```sh
+curl -sL https://talos.dev/install | sh
+```
+
+Verify:
+```sh
+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):**
+```sh
+brew install kubectl
+```
+
+**Linux:** follow the
+[official install instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+for your distribution.
+
+Verify:
+```sh
+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):**
+```sh
+brew install argocd
+```
+
+**Linux:**
+Download the `argocd-linux-amd64` binary from the
+[Argo CD releases page](https://github.com/argoproj/argo-cd/releases), then:
+```sh
+chmod +x argocd-linux-amd64
+sudo mv argocd-linux-amd64 /usr/local/bin/argocd
+```
+
+Verify:
+```sh
+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 --client` works
+- [ ] `kubectl version --client` works
+- [ ] `argocd version --client` works
+- [ ] You have your own fork of this repo cloned locally
+
+Once all of these are true, continue to
+[`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md).