Skip to content

Node upgrade & maintenance

Talos is API-managed and immutable — an upgrade replaces the OS image rather than patching in place. This page is the operational discipline; the exact commands and installer-image schematics live in the talos-cluster README (sections Rolling upgrades, Applying patch changes, Per-node etcd metrics patches).

Golden rules

  • One node at a time. Never script or loop a destructive rollout across nodes — a bad image or a wedged reboot must stop at one node, not cascade. Drive each node by hand and verify before moving on.
  • Talos and Kubernetes minors move together. A Talos upgrade carries a new kubelet, so treat it as a Kubernetes minor too: hold at the current Talos minor until every workload supports the next kubelet version. Clear the compatibility gate first, then upgrade nodes.
  • Privileged Talos operations (talosctl upgrade / apply-config / patch) reboot or rewrite a node — they are run deliberately by an operator, never automated.

Before touching any node

  • Storage is healthy — all Longhorn volumes attached and healthy, no replica rebuild in flight. Rebooting a node mid-rebuild risks the volume (see Storage).
  • Cluster is green — nodes Ready, no pending critical alerts.

Workers

Use the repo's safe-reboot.sh <node> <worker-installer-image> — it drains, evicts, runs talosctl upgrade --preserve, waits for the node to return, and uncordons.

Control-plane nodes

Never run safe-reboot.sh on a control-plane node (it is worker-only by design). Instead, one CP at a time: talosctl upgrade with the control-plane installer image, reboot, then verify etcd quorum + API health and wait ~60 s to settle before the next node. Note two CP-specific traps documented in the README:

  • Some settings (e.g. cluster.etcd.*) only take effect on reboot.
  • A full apply-config of a regenerated controlplane.yaml wipes per-node patches (e.g. the etcd-metrics patches) — re-apply them with the same reboot, or use the README's pre-merge variant.

After the upgrade

  • Bump the local tooling to match the cluster: talosctl, and longhornctl after a Longhorn bump.
  • Update the version references in the repo.

See also: Storage · Operations · Architecture.