Updating Talos Configuration on a Running Kubernetes Cluster

Overview

How to update Talos configuration on a running cluster - adding extensions, changing settings, or upgrading versions. This applies the same workflow from Talhelper Cluster Bootstrap but to an already bootstrapped cluster.

Before You Begin

Prerequisites

Talhelper Cluster Bootstrap completed

When to Use This

Adding system extensions (e.g., iscsi-tools for Longhorn)
Changing network configuration
Updating Talos or Kubernetes versions
Modifying node settings

Example: Longhorn requires iSCSI storage drivers. Without iscsi-tools, the Longhorn manager fails with failed to execute iscsiadm: No such file or directory. Fix by adding the extension and following the workflow below.

Apply Updates

Update Config

Make your changes to talos/talconfig.yaml. Example - adding iscsi-tools extension¹:

schematic:
  customization:
    systemExtensions:
      officialExtensions:
        - siderolabs/i915         # Intel GPU drivers
        - siderolabs/intel-ucode  # Intel CPU microcode
        - siderolabs/iscsi-tools  # iSCSI storage drivers (NEW)

Regenerate Configs

cd ~/homelab/talos

SOPS_AGE_KEY_FILE=<(op document get "sops-key | homelab") \
  talhelper genconfig

Apply to Nodes

talosctl apply-config \
  --nodes 192.168.1.30 \
  --file clusterconfig/homelab-cluster-talos-node-1.yaml

talosctl apply-config \
  --nodes 192.168.1.31 \
  --file clusterconfig/homelab-cluster-talos-node-2.yaml

Upgrade Nodes

apply-config persists the new config but doesn't rebuild the image. For extension changes, trigger an upgrade².


Multi-node:	The upgrade cordons and drains the node first, moving workloads to healthy nodes. Upgrade one node at a time to maintain availability.
Single CP:	When upgrading the control plane node, `kubectl` and API are unavailable during reboot (workloads on worker keep running). With 3 control plane nodes, the API stays available during upgrades.
Remote access:	If using Tailscale subnet router with single replica, draining its node breaks remote access. Ensure local network access during upgrades, or configure Tailscale HA first.

Generate Commands

Use talhelper to generate the upgrade commands³ with correct image URLs:

SOPS_AGE_KEY_FILE=<(op document get "sops-key | homelab") \
  talhelper gencommand upgrade

Run Upgrade

This outputs commands for each node:

talosctl upgrade --talosconfig=./clusterconfig/talosconfig --nodes=192.168.1.30 --image=factory.talos.dev/metal-installer/<SCHEMATIC_ID>:v1.11.6;
talosctl upgrade --talosconfig=./clusterconfig/talosconfig --nodes=192.168.1.31 --image=factory.talos.dev/metal-installer/<SCHEMATIC_ID>:v1.11.6;

Run the commands one node at a time. The upgrade watches automatically - wait for post check passed before upgrading the next node. Expect ~2-3 minutes per node.


Tip:	The `--image` flag is required. Without it, `talosctl upgrade` compares Talos versions. If already at v1.11.6, it skips the upgrade - even if the schematic (extensions) changed. The explicit image forces it.

Verify

# Check extensions on all upgraded nodes
talosctl --nodes 192.168.1.30 get extensions
talosctl --nodes 192.168.1.31 get extensions

# Check nodes are back
kubectl get nodes

# Check cluster health (run against control plane, checks all nodes)
talosctl --nodes 192.168.1.30 health

Commit the Change

Commit Config

git add talos/talconfig.yaml
git commit -m "feat(talos): add <extension> for <purpose>"

Resources

Sidero Labs, "Talos System Extensions," github.com. Accessed: Dec. 18, 2025. [Online]. Available: https://github.com/siderolabs/extensions ↩
Sidero Labs, "Upgrading Talos Linux," docs.siderolabs.com. Accessed: Dec. 18, 2025. [Online]. Available: https://docs.siderolabs.com/talos/v1.9/configure-your-talos-cluster/lifecycle-management/upgrading-talos#talosctl-upgrade ↩
Budimanjojo, "talhelper gencommand," budimanjojo.github.io. Accessed: Dec. 18, 2025. [Online]. Available: https://budimanjojo.github.io/talhelper/latest/reference/cli/#talhelper-gencommand-upgrade ↩