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>
113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# 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).
|