docs: add How Talos Director Works by sterlingkoch · Pull Request #859 · siderolabs/docs

sterlingkoch · 2026-10-08T14:59:52Z

What

A new explanation page, How Talos Director Works, under Overview, plus an intro paragraph on Kubernetes Clusters that points to it.

Why

The Director pages describe the console screen by screen, but nothing explains what is running underneath: what the parts of a deployment are, how a server becomes a host, what happens when a host fails, and how Kubernetes clusters relate to Omni. Evaluators ask these first.

Change

New page public/director/overview/how-talos-director-works.mdx: the parts of a deployment (with a Mermaid diagram), SideroLink and the reverse tunnel, deployment options, the host operating system, how a server becomes a host, compute clusters and scheduling, host failure handling (including local HA mode), storage and networking, VMs and Kubernetes together, upgrades, and what runs where.
Kubernetes Clusters: one intro paragraph saying the lifecycle runs through Omni, nodes are Talos Linux VMs, and existing clusters can be adopted in place, linking to the new page.
Nav entry after What Is Talos Director? in director.yaml, and the regenerated docs.json.

Testing

Ran: make style-check-changed-local, npx mint broken-links, and npx mint dev, with the diagram checked in light and dark mode.
By: an agent (Cursor), reviewed by Sterling.
Result: no style errors, no broken links.
Filled from outside the page: architecture details from engineering review of the Talos Director overview draft. This is the page that most needs an accuracy check from the Director team.

mintlify · 2026-10-08T14:59:56Z

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

Project	Status	Preview	Updated
siderolabs	🟢 Ready	View Preview	Oct 16, 2026, 7:30 AM

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

github-actions · 2026-10-08T15:00:53Z

📋 Automated documentation review

⚠️ The reviewer did not finish on commit 7c67396 (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.

Iheanacho-ai · 2026-10-13T17:09:35Z

+
+## The parts of a deployment
+
+A Talos Director deployment has four parts, connected by two network paths.


what is a Talos director deployment, is it defined anywhere what a Talos director deployment is. im not sure i have seen it

It isn't defined. I'll add it up top: one Talos Director control plane plus the hosts it manages.

Iheanacho-ai · 2026-10-13T17:13:01Z

+
+| **Part** | **Where it runs** | **What it does** |
+| --- | --- | --- |
+| **Talos Linux hosts** | On your servers | Run the virtual machines. Each host is Talos Linux 1.14 or later with the KVM hypervisor, QEMU, and libvirt. There is no shell, no SSH, and no package manager; the host is configured entirely by its machine configuration document. |


a Talos Linux host, as I define it in my other documentation is a physical or virtual server, that runs Talos Hypervisor, and you can create virtual machines off of.

Does this definition differ from how its used here.

If it does not, I thought the minimum requirement was Talos Linux 1.15

Different thing from your hypervisor host. Director hosts run Talos 1.14+ with Director's own agent in the machine config, not the 1.15 Talos Hypervisor APIs. So 1.14 is right here. I'll call them "Talos Director hosts" on this page so the two don't collide.

Iheanacho-ai · 2026-10-13T17:16:44Z

+
+Talos Director brings a bare-metal server under management without anyone touching a keyboard on it.
+
+1. **Register.** Give Talos Director the server's out-of-band management address (iDRAC, iLO, or another Redfish-capable BMC) and credentials.


maybe a lead-in sentence before these numbered steps so that we know what the steps are for.

Iheanacho-ai · 2026-10-13T17:17:36Z

+Talos Director brings a bare-metal server under management without anyone touching a keyboard on it.
+
+1. **Register.** Give Talos Director the server's out-of-band management address (iDRAC, iLO, or another Redfish-capable BMC) and credentials.
+2. **Boot.** Talos Director instructs the BMC to boot the server once from the network, over UEFI HTTP, into a Talos Linux maintenance image prepared for that host.


do you think a colon would be better here instead of a full stop.

so maybe 2. Boot: instead of 2. Boot.

and so on for the rest of the list

Iheanacho-ai · 2026-10-13T17:26:01Z

+
+## What runs where


i am not sure about this title, it does not offer much information about the section it is heading, and i dont think it matches the table.

claude suggested this: Control plane and host responsibilities:

what do you think

Iheanacho-ai · 2026-10-13T17:29:35Z

this is claude's review, i think this review is important to read through

Review: How Talos Director Works

The title fits here. This is a concept page, and "How Talos Director Works" says that plainly. The structure is solid: parts, then lifecycle, then failure handling, then integration, finishing with a summary table. As with the migration page, the problems are contradictions and ambiguous terms.

Code red

The page contradicts itself on upgrades. The host OS section says Talos Director can "upgrade a host by replacing its operating system image while the virtual machines on it keep running." The Upgrades section says it live-migrates the VMs away and reboots the host. Both can't be true. The second is almost certainly right, and the first is misleading.
The "no inbound access" claim doesn't fit BMC onboarding. The page says every management connection is opened by the host and that a hosted control plane "needs no inbound access to your network." But in onboarding step 2, the control plane calls the server's BMC over Redfish, which is an inbound connection to your management network. Either the hosted version handles BMC access some other way, or the claim needs a caveat. Security reviewers will read this sentence closely.
The HA verdict table is incomplete, and one row doesn't make sense.
- Three inputs give eight combinations, but only five are shown. The missing ones include Down / Fresh / No, which is the "agent crashed" case the prose itself describes. What happens there?
- Down / Stale / Yes → "network problem on the observer's side": if peers can reach the host but it isn't writing its datastore heartbeat, the problem looks like the host's storage path, not the observer's network. Ask the engineer.
- "Isolated" is defined as peers can reach the host. That's the opposite of what "isolated" usually means in HA.
Fencing is never explained. The whole split-brain argument depends on fencing, but the page never says how a host is fenced (BMC power-off? storage reservation?) or what happens if fencing fails, for example when the BMC lost power too. The summary table says "fence and restart by host agents," which suggests the agents on other hosts do it. Readers need to know before they trust HA with a database.
"Control plane" means two things. It means the Talos Director control plane throughout, but in the Kubernetes section it also means Kubernetes control plane nodes ("control plane and worker VMs," "the control plane comes up," "control plane address"). On a Talos/Kubernetes page this will confuse people. Call it "the Talos Director control plane" every time, or give it a distinct short name.
"Maintenance mode" also means two things. Onboarding step 3 boots Talos "in maintenance mode" (Talos's unconfigured state). The scheduling section uses "maintenance mode" for draining a host. Readers will conflate them. Rename one, or qualify the Talos one as "Talos maintenance mode."

Accuracy questions

Talos version. "Talos Linux 1.14 or later" appears twice. My notes say native hypervisor support arrives in v1.15. Confirm which version Director requires.
Where the self-hosted control plane runs. On the hosts it manages? On separate machines? The page doesn't say, and readers will ask.
Local HA mode with few hosts. Leader election needs a quorum. What happens in a two-host cluster?
SideroLink's endpoint. The diagram only shows SideroLink to Omni, but the prose says new servers use it to reach Talos Director during onboarding. The diagram is missing that path, or the prose is wrong.
"Four parts, connected by two network paths." A third channel (host-to-host for live migration) is mentioned right after, and the shared storage network isn't counted either. Say "two management paths."
Who forms clusters. The parts table says Omni forms the VMs into clusters. The Kubernetes section says Talos Director forms them "through Omni." Pick one framing.

Structure

Repetition. "No shell, no SSH, no package manager" appears in the parts table and again in the host OS section. "Two hosts with the same profile are configured identically" appears in both the host OS and onboarding sections. Keep one of each.
"Autoscaler" appears once, unexplained. Either introduce it or link to where it's covered.
The last heading. Use Control plane and host responsibilities, as discussed.

Tone

The intro is meta-narration and a bit of coaching: "This page explains how it does it… Read it before the screen-by-screen pages if you want the model the console assumes." Cut it to the cross-link plus one line of scope.
"The properties that make it a stable Kubernetes node make it a stable hypervisor host" reads as a marketing claim. Either back it up or drop it.
"No manual approval is required" and "there is no package transaction that can half-apply" are fine.

Verdict: not ready. Items 1 and 2 are factual contradictions, item 3 or 4 could lead someone to misjudge HA safety, and items 5 and 6 will confuse almost every reader. Once those are fixed, the rest is quick cleanup.

Calls Director hosts Talos Director hosts, defines a deployment, matches the HA table to the decision matrix, covers clusters without a datastore heartbeat, and separates the Director control plane and maintenance mode from their Kubernetes and Talos namesakes. Signed-off-by: Sterling Koch <sterling.koch@siderolabs.com>

Signed-off-by: Sterling Koch <sterling.koch@siderolabs.com>

Iheanacho-ai · 2026-10-16T08:59:02Z

+Talos Director hosts run standard Talos Linux 1.14 or later. The KVM, VFIO, IOMMU, vhost, hugepages, and NUMA support the hypervisor relies on is part of the Talos Linux kernel. Talos Director runs virtual machines through its own host agent, not through the [Talos Hypervisor](/hypervisor/overview/what-is-talos-hypervisor) APIs introduced in Talos Linux 1.15.
+</Note>
+
+## How a server becomes a host


this should be its own page, its way too important to be buried under how talos director works. and what happens when a host fails should be under this.

similar to this page we have in talos hypervisor: https://docs.siderolabs.com/hypervisor/getting-started/install-a-hypervisor-host

we could have it in the getting started page. then users dont miss it when getting started with talos hypervisor, and we can easily link to it in the run your first vm page

Iheanacho-ai · 2026-10-16T09:00:11Z

+
+Talos Director is self-hosted today: the control plane runs in your data center, one per data center, beside the hosts it manages. A version hosted by Sidero Labs is planned, in which Sidero Labs runs the control plane as a service and your hosts stay where they are. In both cases the virtual machines, their disks, and their network traffic stay on your hardware.
+
+## The host operating system


this should also be in the page, about install director on a host or something, the page we plan to carve out of this page.

Iheanacho-ai · 2026-10-16T09:17:16Z

+
+Because a host's entire configuration is one document that Talos Director owns, two hosts in a cluster with the same profile are the same. There is no configuration drift to audit, and replacing a host means running the same six steps again.
+
+## Compute clusters and scheduling


im slightly confused on this section and how it relates to Talos Director. Does Talos director use compute clusters as storage? and if it does, how does this differ from the storage and networking section

sterlingkoch added documentation Improvements or additions to documentation director Talos Director documentation labels Oct 8, 2026

talos-bot added the status/ok-to-test label Oct 8, 2026

talos-bot added this to Planning Oct 8, 2026

sterlingkoch mentioned this pull request Oct 8, 2026

docs: add Coming from VMware, Requirements, and Automation for Talos Director #860

Draft

sterlingkoch added this to Talos Director docs: January Oct 8, 2026

mintlify Bot deployed to staging - public October 8, 2026 15:02

View deployment

smira removed this from Planning Oct 12, 2026

sterlingkoch requested a review from Iheanacho-ai October 13, 2026 10:19

Iheanacho-ai reviewed Oct 13, 2026

View reviewed changes

sterlingkoch added 2 commits October 16, 2026 09:21

docs: add How Talos Director Works

5ef589b

sterlingkoch force-pushed the director/how-it-works-page branch from 7c67396 to da94ada Compare October 16, 2026 07:23

mintlify Bot deployed to staging - public October 16, 2026 07:25

View deployment

docs: explain fencing and the BMC exception on How Talos Director Works

0e9e0b1

Signed-off-by: Sterling Koch <sterling.koch@siderolabs.com>

mintlify Bot deployed to staging - public October 16, 2026 07:30

View deployment

Iheanacho-ai reviewed Oct 16, 2026

View reviewed changes


		## The parts of a deployment

		A Talos Director deployment has four parts, connected by two network paths.


		Talos Director brings a bare-metal server under management without anyone touching a keyboard on it.

		1. Register. Give Talos Director the server's out-of-band management address (iDRAC, iLO, or another Redfish-capable BMC) and credentials.


		Talos Director is self-hosted today: the control plane runs in your data center, one per data center, beside the hosts it manages. A version hosted by Sidero Labs is planned, in which Sidero Labs runs the control plane as a service and your hosts stay where they are. In both cases the virtual machines, their disks, and their network traffic stay on your hardware.

		## The host operating system


		Because a host's entire configuration is one document that Talos Director owns, two hosts in a cluster with the same profile are the same. There is no configuration drift to audit, and replacing a host means running the same six steps again.

		## Compute clusters and scheduling

Conversation

sterlingkoch commented Oct 8, 2026

What

Why

Change

Testing

Uh oh!

mintlify Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 8, 2026

📋 Automated documentation review

Uh oh!

Iheanacho-ai Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Iheanacho-ai Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Iheanacho-ai commented Oct 13, 2026

Review: How Talos Director Works

Code red

Accuracy questions

Structure

Tone

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mintlify Bot commented Oct 8, 2026 •

edited

Loading

Iheanacho-ai Oct 13, 2026 •

edited

Loading

Iheanacho-ai Oct 13, 2026 •

edited

Loading