Skip to content

docs: document the x86-64-v2 CPU requirement - #738

Open
Iheanacho-ai wants to merge 1 commit into
siderolabs:mainfrom
Iheanacho-ai:requirement
Open

docs: document the x86-64-v2 CPU requirement#738
Iheanacho-ai wants to merge 1 commit into
siderolabs:mainfrom
Iheanacho-ai:requirement

Conversation

@Iheanacho-ai

Copy link
Copy Markdown
Member

What

Documents Talos's x86-64-v2 CPU microarchitecture requirement across all 8 live versions (v1.7–v1.14): added to System Requirements, restored on the Proxmox kvm64 workaround (v1.11–v1.14, where it had been dropped), and linked from the GOAMD64 build option in Building Custom Talos Images.

Why

Closes #725. Talos halts at boot below x86-64-v2 with no matching page to land on and no explanation for the existing kvm64/GOAMD64 workarounds — readers hit the wall with no way to search their way out.

Change

  • System Requirements: new "CPU architecture (requirements)" section with the verbatim boot error text, linking to the Proxmox fix and the GOAMD64 option.
  • Proxmox (v1.11–v1.14): restored the "why" next to the kvm64 table row and workaround.
  • Building Custom Talos Images: GOAMD64=v1 now links back to the requirement it works around.

Testing

  • Ran: make broken-links, make validate-docs-nav, make style-check-changed STYLE_CHECK_BASE=upstream/main, make docs.json && git diff --exit-code
  • Where: local checkout
  • By: agent (Claude)
  • Result: all four pass — 0 new style errors/warnings on touched lines, no broken links, nav and docs.json unchanged/current
  • Filled from outside the page: none

@Iheanacho-ai
Iheanacho-ai marked this pull request as draft September 3, 2026 07:01
@github-project-automation github-project-automation Bot moved this to To Do in Planning Sep 3, 2026
@talos-bot talos-bot moved this from To Do to In Review in Planning Sep 3, 2026
@smira smira removed this from Planning Sep 3, 2026
Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
@sterlingkoch

Copy link
Copy Markdown
Member

Read this while it's still in draft, so just notes rather than a review. The substance holds up well.

The version claim checks out on every page you touched. I verified against upstream rather than the release notes alone: GOAMD64 ?= v2 first appears in the v1.1.0 Makefile (v1.0.0 has no GOAMD64 line at all) and is still v2 at every tag from v1.7.0 through v1.14.0. MinimumGOAMD64Level = 2 confirms the level is v2 and not v3, and in v1.14 that constant moved to build-tagged files (constants/amd64.go at level 2 by default, constants/amd64_v1.go at level 1 under //go:build amd64.v1), which independently confirms GOAMD64=v1 really is the documented escape hatch.

The boot error text is byte-identical to the source, and the v1.7 floor is exactly right. The three strings live in internal/app/init/main.go in cpuInfo(), identical in v1.7.0 and v1.14.0, and the [talos] [initramfs] prefix comes from kmsg.SetupLogger. The check itself arrived in siderolabs/talos#8537, milestone v1.7, and is absent from v1.6.0. So starting the quoted error at v1.7 is correct.

All 28 added links resolve. I checked each one mechanically: target file exists in the same version tree, and for anchored links the heading exists in that file and slugifies to the anchor. Zero failures, no cross-version leakage. The two anchor spellings correctly track the two heading spellings, which is the seven-of-eight bug I was looking for and didn't find.

The heading is fine. ## CPU architecture on v1.7 to v1.11 and ## CPU architecture requirements on v1.12 to v1.14 correctly tracks the sentence-case rewrite those newer pages already had (Minimum requirements, Storage requirements). No existing heading was renamed, so no anchor broke.

Two nits for when you mark it ready:

  1. Em dash in the new prose at public/talos/v1.14/getting-started/system-requirements.mdx:90, and the equivalent line in the other seven (v1.7 :84, v1.8 to v1.11 :86, v1.12 and v1.13 :90). House style is a period instead.
  2. don't at building-images.mdx:53 against do not in the System Requirements paragraph. Pick one.

Also worth noting the kvm64 explanation is technically right rather than merely plausible: the flag list already on the page (+cx16,+lahf_lm,+popcnt,+sse3,+ssse3,+sse4.1,+sse4.2) is the x86-64-v2 feature set, so "predates the level Talos requires, add these flags" is the correct causal story.

One thing that is out of scope here, filing separately: As of Talos v1.0 is wrong on the v1.6 through v1.10 Proxmox pages (proxmox.mdx:121, and :93 on v1.6). It should be v1.1.0. Those five files aren't in this diff.

@Iheanacho-ai
Iheanacho-ai marked this pull request as ready for review September 4, 2026 07:51
@github-project-automation github-project-automation Bot moved this to To Do in Planning Sep 4, 2026
@talos-bot talos-bot moved this from To Do to In Review in Planning Sep 4, 2026

For production, it is often more efficient to dedicate a smaller disk for the Talos installation itself, and use additional disks for workload storage. Using a large, single disk for both system and workloads is supported, but may not be optimal depending on your environment.

## CPU architecture

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this applies to amd64 only, arm64 is not covered here

@smira smira removed this from Planning Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the x86-64-v2 CPU requirement

4 participants