docs(install): note the talm version pins on the update path

[Aleksei Sviridkin (lexfrei)]

talm v0.35.0 no longer substitutes a built-in Kubernetes version when templateOptions.kubernetesVersion is empty. This PR documents what that means for projects created with the cozystack preset and how to pin the version.

A Chart.yaml that leaves the key empty still renders while its talosVersion is v1.13 or older. talm emits no image for the kubelet, kube-proxy or the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Raising talosVersion past v1.13 is not a way out of that: above the contract Talos keeps the Kubernetes settings in documents of their own that v0.35.0's charts do not emit, and the render stops whether the Kubernetes version is pinned or not. On the cozystack preset a control-plane node stops earlier still, on the preset's machine.nodeLabels patch, since that label moved out of v1alpha1 at the same contract. The preset pins talosVersion below v1.14, so an untouched project never lands there by itself, but this page tells the reader to raise the key for the v1.12+ link documents, which is how they arrive.

The install guide points readers at the latest talm build, so this is what they get today. The update section now says to pin kubernetesVersion in Chart.yaml to what the cluster actually runs, and not to reach for talosVersion instead. It also covers what talm init --update takes with it: with --force or an accepted prompt it rewrites Chart.yaml, values.yaml and templates/ from the preset and shows no diff, keeping only the chart name. An empty endpoint fails the next render, while an empty floatingIP says nothing and renders with no VIP. Two older lines went with it: the one claiming values.yaml and templates/ customisations survive --update, and the flag list calling --force safe for CI.

The change is applied to next, v1.6, v1.5, v1.4 and v1.3, the docs versions whose page has the update section. Older directories describe an earlier talm and don't have it.

Companion to cozystack/talm#223, released as talm v0.35.0. The talm manual covers the version keys under Talos versions and output format.

[netlify]

✅ Deploy Preview for cozystack ready!

Name	Link
🔨 Latest commit	dec9ef6
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/6ab2f0e57cdda000086c49fe
😎 Deploy Preview	https://deploy-preview-703--cozystack.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 407aeadd-7ba6-49fb-989f-21a60b112ac8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[IvanHunters]

Verdict

NOT LGTM

The paragraph tells a cozystack operator their old project "stops rendering with an error". On the cozystack preset it does not: it renders, drops every Kubernetes component image, and lets each node's Kubernetes version follow its Talos release. That is the quieter and worse of the two outcomes, and the page now says the loud one will happen.

Findings

• [MAJOR] content/en/docs/next/install/kubernetes/talm.md:157, the stated failure mode is not the one a cozystack-preset project gets

• [MAJOR] content/en/docs/v1.6/install/kubernetes/talm.md:157, the stated failure mode is not the one a cozystack-preset project gets

• [MAJOR] content/en/docs/v1.5/install/kubernetes/talm.md:154, the stated failure mode is not the one a cozystack-preset project gets

• [MAJOR] content/en/docs/v1.4/install/kubernetes/talm.md:154, the stated failure mode is not the one a cozystack-preset project gets

• [MAJOR] content/en/docs/v1.3/install/kubernetes/talm.md:154, the stated failure mode is not the one a cozystack-preset project gets

Caveats

• The rest of the paragraph holds up. templateOptions.talosVersion and templateOptions.kubernetesVersion are the real keys (pkg/commands/root.go:112,114), the linked page returns 200 and describes the same mechanism, and --update does rewrite Chart.yaml from the preset, keeping only the cluster name (pkg/commands/init.go:1553-1574), behind the per-file diff prompt the surrounding text already covers.
• Copying the paragraph into each v*/ directory matches CONTRIBUTING.md; v1.2 has no update section to put it in.

[IvanHunters]

[MAJOR] the stated failure mode is not the one a cozystack-preset project gets

The hard error needs talosVersion empty or >= v1.14. Upstream states the condition as a table:

// pkg/engine/contract_validate_render_test.go:208
func TestContract_UnsetKubernetesVersionRefusedOnMultidocContract(t *testing.T) {
	for _, talosVersion := range []string{"", "v1.14"} {

Everything below that contract takes the other branch in pkg/engine/engine.go:2455: a stderr warning, then stripDefaultedImages.

The cozystack preset has never been in the erroring set. talosVersion has carried a pin since the preset was added, and every value is below v1.14:

$ git show 8083090:charts/cozystack/Chart.yaml | grep -E 'talosVersion|kubernetesVersion'   # 2024-05-03, preset added
  talosVersion: "v1.6"
  kubernetesVersion: ""
$ git show e946698:charts/cozystack/Chart.yaml | grep -E 'talosVersion|kubernetesVersion'   # 2025-12-17
  talosVersion: "v1.11"
  kubernetesVersion: ""
$ git show 4e63daa:charts/cozystack/Chart.yaml | grep -E 'talosVersion|kubernetesVersion'   # 2026-01-23, the pin lands
  talosVersion: "v1.11"
  kubernetesVersion: "v1.34.3"

So the projects this page produces (talm init --preset cozystack, line 86; "the production preset used by this guide", line 105) only ever had kubernetesVersion empty, on a contract that warns. charts/generic is the preset that carried both keys empty until v0.35.0, and it is not reachable from here:

$ grep -rn -- '--preset generic' content/en/docs/
$ echo $?
1

What those operators actually face is worth saying, because the current sentence hides it: pre-v0.35.0 talm substituted its own built-in Kubernetes version for an empty key, and v0.35.0 stopped. The same project now renders clean and ships no component images, so the control plane and kubelet start following whatever Talos each node runs, drifting on the next Talos upgrade with nothing in the node file to show it.

Suggested rewording: an old cozystack project renders with a warning: templateOptions.kubernetesVersion is not set on stderr and no pinned component images, which is why kubernetesVersion needs setting; keep "stops rendering" for a project whose talosVersion is also unset.

[Aleksei Sviridkin (lexfrei)]

IvanHunters fixed in c9fcd29. The paragraph now says an old cozystack project still renders, prints a warning on stderr and drops the component images talm would have generated, so each node follows its own Talos release. The hard error is kept only for talosVersion v1.14 or later, or unset. The recovery advice changed too: pin kubernetesVersion in Chart.yaml directly, and compare the result after --update, because an accepted Chart.yaml overwrite replaces the whole file except name and the prompt shows no diff.

One correction to my earlier comment: the preset's pin history is longer than "v1.11 until April". The preset started at talosVersion: "v1.6" in May 2024, as your snippet shows, and went up to v1.12 step by step from there. The conclusion holds either way, every value is below v1.14.

[IvanHunters]

[MAJOR] the stated failure mode is not the one a cozystack-preset project gets

Same text, same issue as content/en/docs/next/install/kubernetes/talm.md:157. The render-stopping error needs talosVersion empty or >= v1.14 (pkg/engine/contract_validate_render_test.go:208 loops exactly {"", "v1.14"}); the cozystack preset has pinned talosVersion below that since it was added, so an old project warns and drops its component images rather than stopping.

[Aleksei Sviridkin (lexfrei)]

Same fix as on next, in c9fcd29.

[IvanHunters]

[MAJOR] the stated failure mode is not the one a cozystack-preset project gets

Same text, same issue as content/en/docs/next/install/kubernetes/talm.md:157. The render-stopping error needs talosVersion empty or >= v1.14 (pkg/engine/contract_validate_render_test.go:208 loops exactly {"", "v1.14"}); the cozystack preset has pinned talosVersion below that since it was added, so an old project warns and drops its component images rather than stopping.

[Aleksei Sviridkin (lexfrei)]

Same fix as on next, in c9fcd29.

[IvanHunters]

[MAJOR] the stated failure mode is not the one a cozystack-preset project gets

Same text, same issue as content/en/docs/next/install/kubernetes/talm.md:157. The render-stopping error needs talosVersion empty or >= v1.14 (pkg/engine/contract_validate_render_test.go:208 loops exactly {"", "v1.14"}); the cozystack preset has pinned talosVersion below that since it was added, so an old project warns and drops its component images rather than stopping.

[Aleksei Sviridkin (lexfrei)]

Same fix as on next, in c9fcd29.

[IvanHunters]

[MAJOR] the stated failure mode is not the one a cozystack-preset project gets

Same text, same issue as content/en/docs/next/install/kubernetes/talm.md:157. The render-stopping error needs talosVersion empty or >= v1.14 (pkg/engine/contract_validate_render_test.go:208 loops exactly {"", "v1.14"}); the cozystack preset has pinned talosVersion below that since it was added, so an old project warns and drops its component images rather than stopping.

[Aleksei Sviridkin (lexfrei)]

Same fix as on next, in c9fcd29.

[Aleksei Sviridkin (lexfrei)]

IvanHunters you're right, and for the reason that matters: the cozystack preset has never had an empty talosVersion. It was v1.11 until April, v1.12 since, so a project from this guide never reaches the hard error, which needs that key empty. Checked the history and rendered it: v1.11 and v1.12 with an empty kubernetesVersion both render and drop the component images, and only talosVersion: "" errors.

Rewrote the paragraph around the outcome this page's readers actually get.

[IvanHunters]

Verdict

NOT LGTM

The v1.13-or-older half of the paragraph is right, and I confirmed every clause of it by building talm from the v0.35.0 tag and running it: exit 0, the warning verbatim on stderr, five component images present when the key is pinned and zero when it is empty. Last round's finding is closed. The other half is not right. The error it quotes never appears on the preset this page is about, and the remedy printed next to it does not unblock that render. Separately, the --update paragraph names three of the eight keys the overwrite takes, and scopes itself to the wrong file.

Findings

• [MAJOR] content/en/docs/next/install/kubernetes/talm.md:157, the v1.14/unset branch quotes an error this preset never emits, and the fix beside it does not unblock the render

• [MAJOR] content/en/docs/next/install/kubernetes/talm.md:157, the restore list names three keys; the overwrite takes five more, including one this page recommends

• [MAJOR] content/en/docs/next/install/kubernetes/talm.md:157, the overwrite is not scoped to Chart.yaml, and the values.yaml loss is silent

• [MINOR] content/en/docs/v1.3/install/kubernetes/talm.md:154, on v1.3, v1.4 and v1.5 this line is the only mention of templateOptions

Caveats

• The v1.14-or-unset branch is not reachable on an untouched preset project, as the PR body says. It is reachable from this page: line 317 tells the reader to raise templateOptions.talosVersion, and a reader upgrading Talos will set it by hand. A branch the page documents is a branch the page has to describe correctly.
• "every node takes the Kubernetes version of the Talos release it happens to run" is exact for the kubelet but loose for kube-proxy and the control-plane statics, which are not per-node settings.
• I did not render the Hugo site (the repo pins a newer Hugo than I have), and the repo ships no markdown lint and no link checker, so nothing in CI holds any of these claims.

[IvanHunters]

[MAJOR] the v1.14/unset branch quotes an error this preset never emits, and the fix beside it does not unblock the render

Built talm from the v0.35.0 tag and ran the whole boundary on a fresh talm init --preset cozystack project. The two branches the sentence draws do not both exist here.

$ talm template --full --offline -f nodes/cp1.yaml   # talosVersion v1.14, kubernetesVersion ""
failed to render templates: applying initial patches: patch delete: path 'machine.nodeLabels.node.kubernetes.io/exclude-from-external-load-balancers' in document '/v1alpha1': failed to delete path '...': lookup failed
exit=1
$ grep -c 'kubernetesVersion is not set' stderr
0
$ # talosVersion "" (unset), kubernetesVersion "": byte-identical error, count 0
$ # talosVersion v1.14, kubernetesVersion "v1.34.3" (PINNED): byte-identical error, count 0

The third line is the one that matters. Pinning the key changes nothing, so templateOptions.kubernetesVersion is not what stops that render, and "Either way, set templateOptions.kubernetesVersion in Chart.yaml" sends the reader to a key that is not in the way. The preset's own $patch: delete on the node label runs before the version gate, and on a >= v1.14 contract that path is gone from v1alpha1.

The quoted string is real, just not here. On --preset generic it is exactly what comes out, and pinning the key there moves you one wall further, to an error whose own hint gives the actual remedy:

$ talm template --full --offline -f nodes/cp1.yaml   # generic, v1.14, kubernetesVersion pinned
failed to render templates: rendered config mixes v1alpha1 fields with the documents that superseded them: ...
hint: templateOptions.talosVersion is v1.14. Pin it to v1.13 or lower in Chart.yaml; above that contract Talos keeps these settings in documents of their own, which the charts do not emit.

So on both presets the fix for the second branch is to keep talosVersion at v1.13 or lower, which is the opposite of what the paragraph tells the reader to do. Suggested shape: keep the first branch as written, and say that above the v1.13 contract v0.35.0's charts do not render at all yet, with the preset failing earlier still on the node-label patch.

[Aleksei Sviridkin (lexfrei)]

IvanHunters same result here. Built talm at the v0.35.0 tag and ran a fresh --preset cozystack project at talosVersion v1.14 and empty, kubernetesVersion pinned and unpinned: all four die at applying initial patches: patch delete: path 'machine.nodeLabels.node.kubernetes.io/exclude-from-external-load-balancers': lookup failed. Machinery fills MachineNodeLabels only below the multidoc contract, and past v1.13 the label lives in KubeNodeConfig.LabelsConfig, so the preset's $patch: delete has nothing to resolve. ApplyPatches also runs long before the version gate, so that gate never gets a turn on this preset. One thing your run did not reach: on a worker node, where the preset emits no nodeLabels, the quoted error is exactly what comes out, and pinning the key then walks into the same mixes v1alpha1 fields wall the generic preset gave you. So the remedy is the same either way.

Fixed in dec9ef6: no quoted error, no kubernetesVersion remedy, and the page now tells the reader not to raise talosVersion past v1.13, with the node-label stop scoped to control-plane nodes. Your kubelet and kube-proxy caveat went in with it.

[IvanHunters]

[MAJOR] the restore list names three keys; the overwrite takes five more, including one this page recommends

Customised a preset project, then ran the command the paragraph is about:

$ talm init --update --preset cozystack --force
Overwriting Chart.yaml (--force)
$ diff -u before/Chart.yaml Chart.yaml
-strictCharts: true
-  kubeconfig: "kubeconfig"
-  valueFiles: [ values-secret.encrypted.yaml ]
+  valueFiles: []
-  timeout: "5m"
+  timeout: "1m"
-  certFingerprints: [ "sha256:deadbeef" ]
+  certFingerprints: []

Five user-set keys are reset on top of the two version pins the paragraph is about. strictCharts: true is what line 166 of this same page tells the reader to set so chart drift hard-fails in CI; it reverts to a warning and nothing says so. certFingerprints is TLS pinning for talm apply. An operator who restores the three named keys ships the other five silently reverted.

[Aleksei Sviridkin (lexfrei)]

Reproduced, and the list was the wrong shape to begin with. updateTalmLibraryChart rebuilds Chart.yaml from the embedded preset and formats only the chart name and version back in, so every other key is gone by construction and any list I write rots. dec9ef6 drops it and says that instead. strictCharts gets its own mention, because the preset does not ship the key at all and it disappears rather than reverting.

[IvanHunters]

[MAJOR] the overwrite is not scoped to Chart.yaml, and the values.yaml loss is silent

Same run, same project, the other file:

$ talm init --update --preset cozystack --force
Overwriting values.yaml (--force)
$ diff -u before/values.yaml values.yaml
-endpoint: "https://10.0.0.1:6443"
+endpoint: ""
-floatingIP: "192.168.1.100"
+floatingIP: ""
-advertisedSubnets:
-  - "10.0.0.0/8"
+advertisedSubnets: []

endpoint fails the next render loudly. floatingIP does not: with endpoint restored and floatingIP left empty the render succeeds, exit 0, no warning, and the generated config carries no VIP at all.

$ talm template --full --offline -f nodes/cp1.yaml ; echo exit=$?
exit=0
$ grep -ci 'vip\|Layer2VIP' rendered.yaml
0

The operator applies that and the control-plane VIP is gone from the machine config. Line 138 of this page already promises that values.yaml customisations survive --update, which is false under --force; that sentence predates this PR, but by warning about Chart.yaml only, the new paragraph makes it read as deliberate scoping rather than a stale claim. Both need to move together.

[Aleksei Sviridkin (lexfrei)]

The overwrite covers every preset-shipped file, not just Chart.yaml. Step 2 of updateTalmLibraryChart loops over all of them, so values.yaml and templates/ go through the same confirmation. I re-ran --update --force with an edited templates/controlplane.yaml and that came back too. dec9ef6 widens the paragraph to all three files and puts the loud endpoint failure next to the silent floatingIP one. The line above it claimed those customisations survive, so it is rewritten in the same commit: of the four files it listed, secrets.yaml and nodes/ are the ones that actually do. The flag list twenty lines up also called --force safe for CI, which is the same claim in a different place, so that went too.

[IvanHunters]

[MINOR] on v1.3, v1.4 and v1.5 this line is the only mention of templateOptions

In those three trees templateOptions and valueFiles each occur exactly once, in this new line:

$ for v in v1.3 v1.4 v1.5; do printf '%s templateOptions=%s valueFiles=%s strictCharts=%s\n' "$v" "$(grep -c templateOptions content/en/docs/$v/install/kubernetes/talm.md)" "$(grep -c valueFiles content/en/docs/$v/install/kubernetes/talm.md)" "$(grep -c strictCharts content/en/docs/$v/install/kubernetes/talm.md)"; done
v1.3 templateOptions=1 valueFiles=1 strictCharts=0
v1.4 templateOptions=1 valueFiles=1 strictCharts=0
v1.5 templateOptions=1 valueFiles=1 strictCharts=0

Those pages document an older talm, carry no chart-drift section, and describe Chart.yaml only as "a file containing the common information about your project". The paragraph tells the reader to compare and restore keys the page never introduces, and it lands between a closing code fence and an unrelated #### Encrypt / Decrypt Round-Trip heading.

[Aleksei Sviridkin (lexfrei)]

Keeping the paragraph on those three. They send the reader to the same hack/install.sh, which pulls the latest build, so the behaviour is theirs too. dec9ef6 makes it self-contained instead: no list of keys to compare, and strictCharts now says what it does where it is named. Placement I would leave alone, it sits under #### Updating to a Newer Talm Release right after that section's commands, and the Encrypt / Decrypt Round-Trip heading after it just starts the next section.