From dec9ef6dc2b0da0801158f65b9e2dd6c7d1db0e2 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Tue, 22 Sep 2026 22:20:09 +0300 Subject: [PATCH] docs(install): note the talm version pins on the update path talm v0.35.0 stops substituting a Kubernetes version when templateOptions.kubernetesVersion is empty. At or below the v1.13 Talos contract the render still succeeds and drops the component images, so Talos picks those versions itself; above it the charts do not render at all, and a cozystack control-plane node fails earlier still on the preset's machine.nodeLabels patch, because that label moved out of v1alpha1 at the same contract. Also correct what `talm init --update` leaves alone. It rewrites every preset-shipped file, values.yaml and templates/ included, so neither the claim that those customisations survive nor the note calling --force safe for CI was right. An empty endpoint fails the next render, but an empty floatingIP renders a machine config with no VIP and says nothing. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin --- content/en/docs/next/install/kubernetes/talm.md | 8 ++++++-- content/en/docs/v1.3/install/kubernetes/talm.md | 8 ++++++-- content/en/docs/v1.4/install/kubernetes/talm.md | 8 ++++++-- content/en/docs/v1.5/install/kubernetes/talm.md | 8 ++++++-- content/en/docs/v1.6/install/kubernetes/talm.md | 8 ++++++-- 5 files changed, 30 insertions(+), 10 deletions(-) diff --git a/content/en/docs/next/install/kubernetes/talm.md b/content/en/docs/next/install/kubernetes/talm.md index 640e360d..34795c1c 100644 --- a/content/en/docs/next/install/kubernetes/talm.md +++ b/content/en/docs/next/install/kubernetes/talm.md @@ -133,9 +133,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. -- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). +- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below. -`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. +`--update` rewrites preset-shipped files: `charts/talm/` outright, and `Chart.yaml`, `values.yaml` and `templates/` behind a per-file prompt that `--force` auto-accepts. Your `secrets.yaml` and `nodes/` are not preset-shipped, so they stay as they are. **Manage encrypted secrets in-place:** @@ -154,6 +154,10 @@ talm init --update --preset cozystack --force # non-interactive: auto-accept al `--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`. +talm v0.35.0 changes what an empty `templateOptions.kubernetesVersion` means. A `Chart.yaml` that leaves the key empty still renders while its `talosVersion` is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin `templateOptions.kubernetesVersion` in `Chart.yaml` to the version the cluster actually runs. Do not raise `templateOptions.talosVersion` above v1.13 to get there: past that 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 or not `kubernetesVersion` is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset's `machine.nodeLabels` patch, because that label moved out of `v1alpha1` at the same contract. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. + +`--update` can undo those pins. With `--force`, or when you accept its prompt for a file, it rewrites `Chart.yaml`, `values.yaml` and `templates/` from the preset without showing a diff; of `Chart.yaml` only the chart `name` survives. Every other key returns to the preset's value: the two version pins, `valueFiles`, the apply timeout, any pinned `certFingerprints`. A key the preset does not ship at all is dropped outright, `strictCharts` among them, so chart drift quietly goes back to being a warning. `values.yaml` is reset the same way: an empty `endpoint` fails the next render, while an empty `floatingIP` does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. Keep both files in git and diff them after every `--update`. + #### Chart Drift Detection (Talm v0.32+) Render commands read the project's local `charts/talm/` copy, never the binary's built-in charts, so upgrading the talm binary does not touch your project — the vendored chart silently goes stale. Release builds of talm detect this and print a non-fatal `WARN:` line on stderr for two independent signals: diff --git a/content/en/docs/v1.3/install/kubernetes/talm.md b/content/en/docs/v1.3/install/kubernetes/talm.md index 1fc334b1..4041b2e4 100644 --- a/content/en/docs/v1.3/install/kubernetes/talm.md +++ b/content/en/docs/v1.3/install/kubernetes/talm.md @@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. -- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). +- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below. -`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. +`--update` rewrites preset-shipped files: `charts/talm/` outright, and `Chart.yaml`, `values.yaml` and `templates/` behind a per-file prompt that `--force` auto-accepts. Your `secrets.yaml` and `nodes/` are not preset-shipped, so they stay as they are. **Manage encrypted secrets in-place:** @@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs ``` +talm v0.35.0 changes what an empty `templateOptions.kubernetesVersion` means. A `Chart.yaml` that leaves the key empty still renders while its `talosVersion` is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin `templateOptions.kubernetesVersion` in `Chart.yaml` to the version the cluster actually runs. Do not raise `templateOptions.talosVersion` above v1.13 to get there: past that 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 or not `kubernetesVersion` is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset's `machine.nodeLabels` patch, because that label moved out of `v1alpha1` at the same contract. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. + +`--update` can undo those pins. With `--force`, or when you accept its prompt for a file, it rewrites `Chart.yaml`, `values.yaml` and `templates/` from the preset without showing a diff; of `Chart.yaml` only the chart `name` survives. Every other key returns to the preset's value: the two version pins, `valueFiles`, the apply timeout, any pinned `certFingerprints`. A key the preset does not ship at all is dropped outright, `strictCharts` among them, so chart drift quietly goes back to being a warning. `values.yaml` is reset the same way: an empty `endpoint` fails the next render, while an empty `floatingIP` does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. Keep both files in git and diff them after every `--update`. + #### Encrypt / Decrypt Round-Trip The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two: diff --git a/content/en/docs/v1.4/install/kubernetes/talm.md b/content/en/docs/v1.4/install/kubernetes/talm.md index 0b832c64..732d50fd 100644 --- a/content/en/docs/v1.4/install/kubernetes/talm.md +++ b/content/en/docs/v1.4/install/kubernetes/talm.md @@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. -- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). +- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below. -`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. +`--update` rewrites preset-shipped files: `charts/talm/` outright, and `Chart.yaml`, `values.yaml` and `templates/` behind a per-file prompt that `--force` auto-accepts. Your `secrets.yaml` and `nodes/` are not preset-shipped, so they stay as they are. **Manage encrypted secrets in-place:** @@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs ``` +talm v0.35.0 changes what an empty `templateOptions.kubernetesVersion` means. A `Chart.yaml` that leaves the key empty still renders while its `talosVersion` is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin `templateOptions.kubernetesVersion` in `Chart.yaml` to the version the cluster actually runs. Do not raise `templateOptions.talosVersion` above v1.13 to get there: past that 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 or not `kubernetesVersion` is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset's `machine.nodeLabels` patch, because that label moved out of `v1alpha1` at the same contract. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. + +`--update` can undo those pins. With `--force`, or when you accept its prompt for a file, it rewrites `Chart.yaml`, `values.yaml` and `templates/` from the preset without showing a diff; of `Chart.yaml` only the chart `name` survives. Every other key returns to the preset's value: the two version pins, `valueFiles`, the apply timeout, any pinned `certFingerprints`. A key the preset does not ship at all is dropped outright, `strictCharts` among them, so chart drift quietly goes back to being a warning. `values.yaml` is reset the same way: an empty `endpoint` fails the next render, while an empty `floatingIP` does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. Keep both files in git and diff them after every `--update`. + #### Encrypt / Decrypt Round-Trip The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two: diff --git a/content/en/docs/v1.5/install/kubernetes/talm.md b/content/en/docs/v1.5/install/kubernetes/talm.md index c418dc1c..ff5fd0ca 100644 --- a/content/en/docs/v1.5/install/kubernetes/talm.md +++ b/content/en/docs/v1.5/install/kubernetes/talm.md @@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. -- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). +- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below. -`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. +`--update` rewrites preset-shipped files: `charts/talm/` outright, and `Chart.yaml`, `values.yaml` and `templates/` behind a per-file prompt that `--force` auto-accepts. Your `secrets.yaml` and `nodes/` are not preset-shipped, so they stay as they are. **Manage encrypted secrets in-place:** @@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs ``` +talm v0.35.0 changes what an empty `templateOptions.kubernetesVersion` means. A `Chart.yaml` that leaves the key empty still renders while its `talosVersion` is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin `templateOptions.kubernetesVersion` in `Chart.yaml` to the version the cluster actually runs. Do not raise `templateOptions.talosVersion` above v1.13 to get there: past that 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 or not `kubernetesVersion` is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset's `machine.nodeLabels` patch, because that label moved out of `v1alpha1` at the same contract. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. + +`--update` can undo those pins. With `--force`, or when you accept its prompt for a file, it rewrites `Chart.yaml`, `values.yaml` and `templates/` from the preset without showing a diff; of `Chart.yaml` only the chart `name` survives. Every other key returns to the preset's value: the two version pins, `valueFiles`, the apply timeout, any pinned `certFingerprints`. A key the preset does not ship at all is dropped outright, `strictCharts` among them, so chart drift quietly goes back to being a warning. `values.yaml` is reset the same way: an empty `endpoint` fails the next render, while an empty `floatingIP` does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. Keep both files in git and diff them after every `--update`. + #### Encrypt / Decrypt Round-Trip The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two: diff --git a/content/en/docs/v1.6/install/kubernetes/talm.md b/content/en/docs/v1.6/install/kubernetes/talm.md index bf1f1e55..365d2083 100644 --- a/content/en/docs/v1.6/install/kubernetes/talm.md +++ b/content/en/docs/v1.6/install/kubernetes/talm.md @@ -133,9 +133,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. -- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). +- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below. -`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. +`--update` rewrites preset-shipped files: `charts/talm/` outright, and `Chart.yaml`, `values.yaml` and `templates/` behind a per-file prompt that `--force` auto-accepts. Your `secrets.yaml` and `nodes/` are not preset-shipped, so they stay as they are. **Manage encrypted secrets in-place:** @@ -154,6 +154,10 @@ talm init --update --preset cozystack --force # non-interactive: auto-accept al `--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`. +talm v0.35.0 changes what an empty `templateOptions.kubernetesVersion` means. A `Chart.yaml` that leaves the key empty still renders while its `talosVersion` is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin `templateOptions.kubernetesVersion` in `Chart.yaml` to the version the cluster actually runs. Do not raise `templateOptions.talosVersion` above v1.13 to get there: past that 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 or not `kubernetesVersion` is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset's `machine.nodeLabels` patch, because that label moved out of `v1alpha1` at the same contract. [Talos versions and output format](https://talm.cozystack.io/configuration/talos-versions/) explains what each key selects. + +`--update` can undo those pins. With `--force`, or when you accept its prompt for a file, it rewrites `Chart.yaml`, `values.yaml` and `templates/` from the preset without showing a diff; of `Chart.yaml` only the chart `name` survives. Every other key returns to the preset's value: the two version pins, `valueFiles`, the apply timeout, any pinned `certFingerprints`. A key the preset does not ship at all is dropped outright, `strictCharts` among them, so chart drift quietly goes back to being a warning. `values.yaml` is reset the same way: an empty `endpoint` fails the next render, while an empty `floatingIP` does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. Keep both files in git and diff them after every `--update`. + #### Chart Drift Detection (Talm v0.32+) Render commands read the project's local `charts/talm/` copy, never the binary's built-in charts, so upgrading the talm binary does not touch your project — the vendored chart silently goes stale. Release builds of talm detect this and print a non-fatal `WARN:` line on stderr for two independent signals: