vps-k8s/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 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) 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 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. 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.

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.
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.

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):

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

• 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.