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, replace `<NODE_IP>` with your machine's real IP address. If it's
a VM, give it a DHCP reservation (a fixed IP tied to its MAC address) in your
router or hypervisor before you start, so the address never changes under
the cluster. Talos bakes the IP into certificates during setup, and changing
it later means starting over.

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

## 1. Generate machine configuration

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

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 full machine configuration for a control-plane
  node, with our single-node patch baked in.
- `worker.yaml` — a worker machine configuration. Unused for now (single
  node), kept for when you follow docs/08-growing-up.md.
- `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. `https://<NODE_IP>:6443` is the cluster's Kubernetes
API endpoint: port 6443 is the standard Kubernetes API server port, and this
same address gets written into the certificates and your future kubeconfig.

## 2. Point talosctl at this cluster

```sh
export TALOSCONFIG=_out/talosconfig
talosctl config endpoint <NODE_IP>
talosctl config node <NODE_IP>
```

`endpoint` is which machine talosctl *talks to*. `node` is which machine a
command *applies to*. On a single-node cluster they're the same address, but
Talos always keeps the two concepts separate, because on a multi-node
cluster you often want to ask one node about another.

## 3. Apply the configuration

Boot the target machine from the Talos ISO (see
[docs/01-prerequisites.md](../docs/01-prerequisites.md) for where to get it).
It boots into "maintenance mode" — alive enough to accept a configuration,
with nothing installed yet. Confirm it's reachable, then apply:

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

Note the disk name you want Talos installed to (e.g. `/dev/sda`). Then:

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

`--insecure` is required for this one command only: the node has no
certificates yet, so talosctl can't authenticate to it normally. This is
the one moment during setup where you're trusting the network — do this on
a network you control. The node will reboot, install Talos to disk, and
come back up running the configuration you gave it — now *with*
certificates, so every command after this uses the secure path.

## 4. Bootstrap etcd

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

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

Run this exactly once per cluster, against exactly one control-plane node,
even if you later add more. Running it again on an existing cluster can
corrupt it.

## 5. Get your kubeconfig

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

Downloads a kubeconfig into the current directory (also gitignored —
it grants full cluster access). 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 one node, `Ready`, within a couple of minutes (it takes a
moment for the default CNI — Talos ships Flannel out of the box — to come
up and clear the node's networking checks).

```
NAME              STATUS   ROLES           AGE   VERSION
talos-...         Ready    control-plane   90s   v1.3x.x
```

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