docs(install): note the talm version pins on the update path - #703
Aleksei Sviridkin (lexfrei) wants to merge 2 commits into
Conversation
talm v0.35.0 stops rendering a project whose templateOptions.talosVersion or templateOptions.kubernetesVersion is empty, which is every project created before the presets carried those pins. The install guide sends readers to the latest talm build, so it needs to say what the re-sync brings with it. Applied to every docs version whose page carries the update section. Signed-off-by: Aleksei Sviridkin <f@lex.la> Assisted-by: LLM
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Advanced Run ID: 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. Comment |
IvanHunters
left a comment
IvanHunters
left a comment
There was a problem hiding this comment.
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.talosVersionandtemplateOptions.kubernetesVersionare the real keys (pkg/commands/root.go:112,114), the linked page returns 200 and describes the same mechanism, and--updatedoes rewriteChart.yamlfrom 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 matchesCONTRIBUTING.md;v1.2has no update section to put it in.
|
|
||
| `--update` re-syncs the vendored `charts/talm/` exactly — files that the new library no longer ships (or strays like `.DS_Store`) are pruned — and advances the preset baseline in `.talm-preset.lock`. | ||
|
|
||
| From talm v0.35.0 both version keys have to be pinned. `templateOptions.talosVersion` and `templateOptions.kubernetesVersion` used to work when left empty, and a project created before the presets carried pins now stops rendering with an error naming the key to set. `--update` rewrites `Chart.yaml` from the preset and brings the preset's pins with it, so check `kubernetesVersion` against what your cluster actually runs rather than keeping whatever the re-sync wrote. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. |
There was a problem hiding this comment.
[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 $?
1What 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.
|
|
||
| `--update` re-syncs the vendored `charts/talm/` exactly — files that the new library no longer ships (or strays like `.DS_Store`) are pruned — and advances the preset baseline in `.talm-preset.lock`. | ||
|
|
||
| From talm v0.35.0 both version keys have to be pinned. `templateOptions.talosVersion` and `templateOptions.kubernetesVersion` used to work when left empty, and a project created before the presets carried pins now stops rendering with an error naming the key to set. `--update` rewrites `Chart.yaml` from the preset and brings the preset's pins with it, so check `kubernetesVersion` against what your cluster actually runs rather than keeping whatever the re-sync wrote. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. |
There was a problem hiding this comment.
[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.
| talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs | ||
| ``` | ||
|
|
||
| From talm v0.35.0 both version keys have to be pinned. `templateOptions.talosVersion` and `templateOptions.kubernetesVersion` used to work when left empty, and a project created before the presets carried pins now stops rendering with an error naming the key to set. `--update` rewrites `Chart.yaml` from the preset and brings the preset's pins with it, so check `kubernetesVersion` against what your cluster actually runs rather than keeping whatever the re-sync wrote. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. |
There was a problem hiding this comment.
[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.
| talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs | ||
| ``` | ||
|
|
||
| From talm v0.35.0 both version keys have to be pinned. `templateOptions.talosVersion` and `templateOptions.kubernetesVersion` used to work when left empty, and a project created before the presets carried pins now stops rendering with an error naming the key to set. `--update` rewrites `Chart.yaml` from the preset and brings the preset's pins with it, so check `kubernetesVersion` against what your cluster actually runs rather than keeping whatever the re-sync wrote. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. |
There was a problem hiding this comment.
[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.
| talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs | ||
| ``` | ||
|
|
||
| From talm v0.35.0 both version keys have to be pinned. `templateOptions.talosVersion` and `templateOptions.kubernetesVersion` used to work when left empty, and a project created before the presets carried pins now stops rendering with an error naming the key to set. `--update` rewrites `Chart.yaml` from the preset and brings the preset's pins with it, so check `kubernetesVersion` against what your cluster actually runs rather than keeping whatever the re-sync wrote. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. |
There was a problem hiding this comment.
[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.
The paragraph described the hard error, which needs an empty templateOptions.talosVersion. The cozystack preset has always pinned that key (v1.11 before April, v1.12 after), so a project from this guide never hits it. What it gets is the quiet path: the render succeeds, ships no Kubernetes component images, and every node follows the Talos release it runs. Signed-off-by: Aleksei Sviridkin <f@lex.la> Assisted-by: LLM
|
IvanHunters you're right, and for the reason that matters: the cozystack preset has never had an empty Rewrote the paragraph around the outcome this page's readers actually get. |
2 participants
talm v0.35.0 refuses to render a project whose
templateOptions.talosVersionortemplateOptions.kubernetesVersionis empty. That is every project created before the shipped presets carried those pins, and the error names the key to set.The install guide points readers at the latest talm build, so the version they get today is the one with this behaviour. The update section already covers what
talm init --update --preset cozystackdoes to the vendored chart; it now also says that the re-sync brings the preset's version pins along, and thatkubernetesVersionis worth checking against what the cluster actually runs rather than kept as written.Applied to
next,v1.6,v1.5,v1.4andv1.3— every docs version whose page carries the update section. The older directories describe an earlier talm and do not have it.Companion to cozystack/talm#223, released as talm v0.35.0. The full reasoning lives in the talm manual under Talos versions and output format.