k8s-starter-pack/talos/README.md

# Talos bootstrap — command reference

This is the detailed, copy-pasteable companion to
[`docs/02-talos-bootstrap.md`](../docs/02-talos-bootstrap.md). Read that file
first for the explanations — this one is here so you have every exact
command in one place once you understand what they do.

Throughout, use the three control-plane and two worker addresses recorded in
[`docs/network.md`](../docs/network.md), plus the cluster's shared VIP. Give
each machine a DHCP reservation (a fixed IP tied to its MAC address) before
installation so its address remains stable.

Steps 1–2 below run **once, total**. Step 3 runs **once per node** (five
times, using the matching role configuration). Steps 4–6 run **once, total**;
Talos API commands target a control-plane node, while Kubernetes uses the VIP.

All commands assume you're running them from the root of this repo.

## 1. Generate machine configuration

```sh
talosctl gen config gitops-starter https://<VIP_IP>:6443 \
  --output-dir _out \
  --config-patch-control-plane @talos/patch-controlplane.yaml \
  --config-patch-control-plane @talos/patch-netbird.yaml \
  --config-patch-worker @talos/patch-worker.yaml \
  --config-patch-worker @talos/patch-longhorn.yaml \
  --config-patch-worker @talos/patch-netbird.yaml
```

Note the cluster endpoint here is the **VIP**, not any one node's address
— every node needs to agree in advance on where the cluster "lives," and
that address has to be the one that keeps working no matter which node is
currently answering.

This writes three files into `_out/` (already covered by this repo's
`.gitignore` — they contain private keys and must never be committed):

- `controlplane.yaml` — the machine configuration for a control-plane
  node, with the Raspberry Pi/VIP and non-secret NetBird patches baked in.
  It is applied identically to all three control-plane nodes.
- `worker.yaml` — the machine configuration for the two Proxmox workers,
  with their role, Longhorn data-disk, and non-secret NetBird patches baked
  in. The NetBird setup key is deliberately absent from both generated files;
  enrollment uses a short-lived key applied separately and revoked afterward.
- `talosconfig` — *your* client credentials for talking to the Talos API on
  this cluster (equivalent in spirit to a kubeconfig, but for Talos itself
  rather than Kubernetes).

`gitops-starter` is the cluster name — an arbitrary label baked into the
generated certificates and config, used to tell clusters apart if you ever
manage more than one. Port 6443 is the standard Kubernetes API server port.

## 2. Point talosctl at this cluster

```sh
export TALOSCONFIG=_out/talosconfig
talosctl config endpoint <NODE1_IP> <NODE2_IP> <NODE3_IP>
```

`endpoint` is which machine(s) talosctl is willing to *talk to* — giving
it all three means it can still reach the cluster if any one of them is
down. You'll pass `--nodes` per-command below for which machine a given
command actually *applies to* — Talos always keeps those two concepts
separate.

## 3. Apply the configuration — once per node

Boot each machine from its architecture-appropriate custom Talos image (see
[docs/01-prerequisites.md](../docs/01-prerequisites.md)). Each boots into
"maintenance mode" — alive enough to accept configuration, with nothing
installed yet. Inspect its disks first:

```sh
talosctl get disks --insecure --nodes <NODE_IP>
```

For each Raspberry Pi control plane, confirm `/dev/mmcblk0` is the intended
system disk, then apply the control-plane configuration:

```sh
talosctl apply-config --insecure \
  --nodes <CONTROL_PLANE_IP> \
  --file _out/controlplane.yaml
```

For each Proxmox worker, confirm `/dev/sda` is the Talos system disk and
`/dev/sdb` is the dedicated Longhorn disk selected by
`talos/patch-longhorn.yaml`, then apply the worker configuration:

```sh
talosctl apply-config --insecure \
  --nodes <WORKER_IP> \
  --file _out/worker.yaml
```

`--insecure` is required for this one command only: the node has no
certificates yet, so talosctl cannot authenticate to it normally. This is
the one moment during setup where you trust the local network. After applying
configuration, the node installs Talos and returns with authenticated API
access. Configure all three control planes and both workers before continuing.

## 4. Bootstrap etcd — once, total

Talos is installed on all three nodes and Kubernetes components are
starting, but the cluster has no data store yet. This one-time command
initializes it:

```sh
talosctl bootstrap --nodes <NODE1_IP>
```

Run this **exactly once**, against **exactly one** of your three nodes —
even though all three will end up running etcd as peers, only one needs
telling to *start* the cluster; the other two discover and join the
existing one. Running it again against an existing cluster can corrupt it.

## 5. Get your kubeconfig

```sh
talosctl kubeconfig --nodes <CONTROL_PLANE_IP> .
```

Downloads a kubeconfig through a control-plane node's Talos API into the
current directory (also gitignored — it grants full cluster access). The
resulting Kubernetes configuration points at the cluster VIP rather than one
specific control plane. Merge it with `~/.kube/config` or point `KUBECONFIG`
at it directly:

```sh
export KUBECONFIG=$PWD/kubeconfig
```

## 6. Verify

```sh
kubectl get nodes
```

Expect to see **five** nodes, `Ready`, within a couple of minutes (it takes
a moment for the default CNI — Talos ships Flannel out of the box — to clear
each node's networking checks).

```text
NAME              STATUS   ROLES           AGE   VERSION
talos-...         Ready    control-plane   90s   v1.3x.x
talos-...         Ready    control-plane   85s   v1.3x.x
talos-...         Ready    control-plane   80s   v1.3x.x
talos-...         Ready    worker          75s   v1.3x.x
talos-...         Ready    worker          70s   v1.3x.x
```

If any node is stuck on `NotReady`, give it another minute before
troubleshooting — first boot does a lot of one-time work.