155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# 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.
|