k8s-starter-pack/docs/01-prerequisites.md

# 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. Three target machines

This repo builds a **three-node cluster**, with every node acting as both
control plane (the brain: API server, scheduler, the cluster's own
database) and worker (runs your actual apps) at once. Three, not one,
because it's the smallest number where losing any single machine doesn't
take the whole cluster down — see
[`docs/00-what-is-all-this.md`](00-what-is-all-this.md) for why three
specifically, not two or four.

You need three machines — spare physical PCs, mini PCs, or VMs (VirtualBox,
UTM, Proxmox, or any hypervisor that can boot from an ISO). Minimum
realistic spec per machine: 2 CPU cores, 4GB RAM, plus **two disks each**:
one for Talos itself (20GB+ is plenty), and a second, separate disk of
**at least 900GB** that will be handed entirely to Longhorn
(see [`docs/06-longhorn.md`](06-longhorn.md)) for storage. If your spare
hardware doesn't have a second disk that large, that's a real constraint —
ask Claude about adjusting the size threshold in
[`talos/patch-longhorn.yaml`](../talos/patch-longhorn.yaml) to fit what you
actually have.

Each machine needs to be reachable over the network from your everyday
machine (the one you'll run `talosctl` and `kubectl` from), and each needs
its own stable IP address — see the note about DHCP reservations in
[`talos/README.md`](../talos/README.md). You'll also need one *additional*
unused address for the cluster's shared VIP (Virtual IP) — more on that in
[`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md).

You do **not** need to install an OS on any of them 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.

### Building your Talos image

Stock Talos doesn't include everything Longhorn needs — specifically, the
`iscsi-tools` and `util-linux-tools` **system extensions** (optional
add-ons baked into the boot image itself, since Talos has no package
manager to install them onto a running node). You build a custom image,
called a **schematic**, once, and use it for all three nodes:

1. Go to [factory.talos.dev](https://factory.talos.dev).
2. Under system extensions, select `siderolabs/iscsi-tools` and
   `siderolabs/util-linux-tools`.
3. Pick the current stable Talos version and `metal-amd64` as the platform.
4. Download the resulting ISO (the site calls this a "schematic" —
   your own custom Talos image, identified by a schematic ID).

Boot **all three** machines from this same ISO, and leave each sitting at
its boot screen — you'll configure them in
[`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md).

> **Ask Claude:** if you're not sure whether to use VMs or spare physical
> hardware, ask — the tradeoffs (snapshots and easy resets vs. more
> realistic networking, and whether three VMs on one physical host really
> gives you the resilience three nodes are supposed to buy you) 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

- [ ] Three target machines chosen, each network-reachable, each with a
      stable IP address noted, each with a second disk ≥900GB for Longhorn
- [ ] One additional unused IP address set aside for the cluster's VIP
- [ ] Custom Talos schematic built at factory.talos.dev with `iscsi-tools`
      and `util-linux-tools`, ISO downloaded
- [ ] All three machines booted from that ISO, 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).