[lee-peal]

What

Adds a page explaining how to upgrade Talos Director hosts: the operating system, the host agent, and the witness.

Why

No page in the docs covers upgrading Talos Director hosts. The Clusters and Hosts pages each mention their Updates tab only briefly, with nothing on image lanes, agent upgrades, rollback, or what to do when an upgrade fails.

Addresses issue #817.

Change

• New page public/director/compute/upgrade-hosts.mdx, a how-to page (Diátaxis type: how-to) that covers:
  • Components: what each one is, how upgrading it affects the host, and where to upgrade it
  • Before you begin: capacity, connectivity, and release-note checks
  • Image lanes: the cluster's machine config profile panel
  • Rolling OS upgrade: steps, plus what Talos Director does on each host
  • Single-host upgrade: the host Updates tab panels, upgrading a host, and rolling it back
  • Rolling agent upgrade: fields, per-host phases, and reverting
  • Troubleshooting: common failure messages and what to do
• Nav: Added the page to the Director Compute group in director.yaml, after Hosts.
• public/docs.json: Regenerated. The only change is the new page entry.

Testing

• Ran: docs.json generation, check-missing, validate-docs-nav, canonical-links-check, check-frontmatter-changed and style-check-changed, using Linux builds of the repo's Go tools.
• Where: A local checkout on Windows, with the checks run under WSL (Linux). Schema validation ran on Windows because WSL couldn't reach the schema URL.
• By: An agent (Claude Code), reviewed by me.
• Result: All checks pass, and the style check reports 0 errors and 0 warnings. make broken-links was not run locally because Docker wasn't available. The page's only link points to a heading on the same page.
• Filled from outside the page: Nothing. The console paths and field names come from the source draft, and the Compute > All Host Clusters path was confirmed by the author.

[github-actions]

📋 Automated documentation review

⚠️ The reviewer did not finish on commit 240e223 (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
siderolabs	🟢 Ready	View Preview	Nov 11, 2026, 8:39 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[Iheanacho-ai]

this page does not talk about how to upgrade the witness, is that deliberate?

[Iheanacho-ai]

i think the structure of this doc is a tad bit off, this is a structure id suggest:

• Components
• Before you begin
• Image lanes
• Upgrade the OS
  • Upgrade a single host
  • Run a rolling upgrade
  • Roll back a host
• Upgrade the host agent
  • Run a rolling upgrade
  • Revert an agent upgrade
• Troubleshoot a failed upgrade

[Iheanacho-ai]

i also put this doc in claude for correctnees and structure review and this is the output, you can reason through this review and figure out which ones youd like to implement or not:

This is the same text as last time, so none of the earlier points have been addressed yet. The short version, with the new page order included:

Must fix

1. Rolling OS upgrade has no "pick a version" step. Say where the target comes from, probably the lane's Install image.
2. Maintenance mode contradicts itself. The rolling steps move on to the next host, but the Last OS upgrade example says the host is "left in maintenance". Confirm which is right.
3. Clashes with hosts.mdx.
   • The button is Run Update there and Upgrade… here.
   • hosts.mdx says to migrate VMs yourself; this page implies it's automatic.
   • hosts.mdx links to clusters#updates, not this page.
4. Wrong navigation path. Use Compute > Clusters, not All Host Clusters.
5. Single host vs lane. Does the lane overwrite a host that was upgraded to a different version?

Structure

8. Link the two OS upgrades. Single-host is for testing and rolling is for rolling out, so point each one at the other.