Upgrade Talos Cluster Version Using Tofu

This guide walks through how I safely upgrade my Talos Kubernetes cluster to a new version using Tofu. The process upgrades each node individually by setting update = true, and only updates the version once all nodes have been upgraded.

info

Never revert update to false before completing the upgrade across all nodes. Doing so will recreate that node using the older version.

Prerequisites

tofu CLI installed and authenticated
Existing Talos cluster deployed using Tofu and modules
The desired Talos version defined in update_version under image
Backup etcd snapshots or ensure application tolerance to node recreation

Overview of workflow

Sequentially set update = true on each node, one at a time
Run tofu apply after each change to upgrade that node
After all nodes have update = true and are upgraded, change the version fields
Reset all update flags to false
Final tofu apply to persist the upgrade state

Upgrade one node at a time

Edit main.tf: Set update = true for the first node.
```
"ctrl-00" = {
  ...
  update = true
}
```
Apply the change:
```
tofu apply
```
Verify the node is back online and healthy:
```
talosctl -n 10.25.150.11 get machines
```
Repeat steps 1–3 for the next node, adding update = true without modifying previous ones. Do not set update = false on any already-upgraded nodes.

Example after upgrading two nodes:
```
"ctrl-00" = {
  ...
  update = true
}

"ctrl-01" = {
  ...
  update = true
}
```
Continue until all nodes (control plane and worker) have update = true.

Finalize the version change

Edit main.tf and set the permanent Talos version:

image = {
  version        = "v1.10.2"
  update_version = "v1.10.2"
  ...
}

cluster = {
  ...
  talos_version = "v1.10.2"
}

Reset all nodes’ update flags back to false:
```
"ctrl-00" = {
  ...
  update = false
}
```
Apply the final state:
```
tofu apply
```

Verify the upgrade

Check Talos version on each node:
```
talosctl version -n <node-ip>
```
Output should show v1.10.2 for every node.
Verify Kubernetes nodes:
```
kubectl get nodes -o wide
```
Confirm all nodes are Ready and on the expected version.

Optional: Revert a node (rollback)

If you need to rollback a specific node before finalizing the version:

Leave version untouched
Set that node’s update = false
Run tofu apply

This recreates the node using the version, effectively rolling it back.

Prerequisites​

Overview of workflow​

Upgrade one node at a time​

Finalize the version change​

Verify the upgrade​

Optional: Revert a node (rollback)​