docs (talos hvm): add the Virtual Machines pages for Talos Hypervisor

[Iheanacho-ai]

What

Adds the Virtual Machines section for Talos Hypervisor:

• create-and-configure-a-virtual-machine.mdx: declare a virtual machine with a VirtualMachineConfig document, and configure its power state, processors, memory, firmware, disks, serial console, and network interfaces. Covers how patches merge, when a change replaces or stops a running virtual machine, and how to remove one.
• access-the-virtual-machine-console.mdx: enable the serial console, attach to it with talosctl hypervisor console, and read its kept output with talosctl logs --kind=vm.
• check-virtual-machine-status.mdx: read VirtualMachineStatus, VirtualMachineDiskStatus, and VirtualMachineDomainStatus, including what each stage means.

Why

This is part of the Talos Hypervisor docs for TalosCon. It builds on the navigation in #805, and the combined PR at the end will bring all of the Talos Hypervisor PRs to main.

Change

• public/hypervisor/virtual-machines/create-and-configure-a-virtual-machine.mdx: new page.
• public/hypervisor/virtual-machines/access-the-virtual-machine-console.mdx: new page.
• public/hypervisor/virtual-machines/check-virtual-machine-status.mdx: new page.

TODO comments mark content to add or verify later: writable disks in storage pools (siderolabs/talos#14573), UEFI firmware and secure boot (not covered by the hypervisor integration tests), VNC (not reachable from outside the host), and the role required by talosctl logs --kind=vm.

Testing

• Ran: make style-check-changed. Every YAML block was loaded and validated with Talos's own config loader and validator, including a single VirtualMachineConfig that uses every field documented on the create page. The $patch: delete file was applied with Talos's patch loader.

• Where: local checkout, against siderolabs/talos main at 8fca673 and siderolabs/extensions main at 7d75c4b

• By: an agent (Claude Code), plus a separate agent that fact-checked all three pages against the source, citing file:line

• Result: the style check passes and every YAML block validates. The fact-check confirmed the console page and most of the create page. It found errors and gaps, all corrected:

  • A stopped virtual machine shows the unknown stage, not ready, and the stage meanings were made precise.
  • Only cdrom disks are provisioned, and type defaults to disk.
  • A running virtual machine is stopped when Talos can no longer build its definition.
  • Stopping and removing are forced power-offs.
  • A patch cannot remove a disk.
  • Ballooning, firmware changes, and boot order had been overstated.
  • Console output is kept only while the serial console is enabled.

  The commands have not been run on a host, because there is no Talos v1.15 alpha build yet. The frontmatter check reports the pages as belonging to no known section until docs (talos hvm): add the Talos Hypervisor navigation structure #805 merges. broken-links will flag the links to the Storage pages, which are in a separate PR, and the v1.15 reference link until the Talos v1.15 docs are added.

• Filled from outside the page: nothing. All behavior comes from the Talos source.

[github-actions]

📋 Automated documentation review

An automated pass runs on documentation changes in every PR. The items below are suggestions to consider — advisory, not a merge gate.

Reviewed commit e52c78f · 🔴 0 critical · 🟡 5 warning(s) · ⚪ 4 notice(s)

• 🟡 public/hypervisor/virtual-machines/create-and-configure-a-virtual-machine.mdx:12 — Link to the VirtualMachineConfig reference points at a talos/v1.15 tree that does not exist in this repo.
  • Why: There is no public/talos/v1.15/ directory (newest is v1.14, which has no reference/configuration/hypervisor/ subdirectory), so the page's only link to the authoritative field reference 404s and make broken-links fails.
  • Fix: Land the v1.15 hypervisor configuration reference in the same change, or link to an existing page until it exists.
• 🟡 public/hypervisor/virtual-machines/create-and-configure-a-virtual-machine.mdx:122 — Link to ../storage/upload-and-manage-images targets a page that does not exist.
  • Why: public/hypervisor/storage/ does not exist in this repo; public/hypervisor/ contains only the files added by this PR, so the link 404s and make broken-links fails.
  • Fix: Merge the hypervisor storage pages in the same change, or drop the cross-reference until they exist.
• 🟡 public/hypervisor/virtual-machines/create-and-configure-a-virtual-machine.mdx:161 — Advice to remove a disk with talosctl apply-config omits that it replaces the entire machine configuration.
  • Why: talosctl apply-config replaces the whole machine config, not just the VirtualMachineConfig documents; a reader who applies a file containing only the VM document would wipe the node's cluster and machine configuration.
  • Fix: State that apply-config replaces the entire machine configuration and show the safe flow: export with talosctl get machineconfig -o yaml, remove the disk entry, then talosctl apply-config --nodes --file .yaml.
• 🟡 public/hypervisor/virtual-machines/create-and-configure-a-virtual-machine.mdx:1 — The three new hypervisor pages are not listed in any navigation YAML.
  • Why: No root nav YAML covers public/hypervisor/**; director.yaml maps to director/ and common.yaml declares Talos Hypervisor only as a soon:true homepage card, so these pages are unreachable on the site and make check-missing and make validate-docs-nav will fail.
  • Fix: Add a hypervisor.yaml nav file listing these pages, add it to the docs.json and check-missing file lists in the Makefile, and commit the regenerated public/docs.json.
• 🟡 public/hypervisor/virtual-machines/check-virtual-machine-status.mdx:57 — Both Related resources links point at hypervisor storage pages that do not exist.
  • Why: public/hypervisor/storage/upload-and-manage-images and create-a-storage-pool are absent from the repo, so both links 404 and make broken-links fails.
  • Fix: Land the hypervisor storage pages in the same change, or remove the Related resources section until they exist.

Notices, and the reviewer's full report, are in the run's doc-accuracy-report artifact.

[github-actions]

📋 Automated documentation review

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

[sterlingkoch]

Merged as part of #867.