Skip to content

Commit 73a9780

Browse files
committed
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. The preset image comes back too, and talm upgrade reads its target from values.yaml, so an unrestored pin downgrades nodes running a newer Talos. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 57b2e75 commit 73a9780

5 files changed

Lines changed: 30 additions & 10 deletions

File tree

‎content/en/docs/next/install/kubernetes/talm.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,9 +133,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e
133133
**Update an existing project to the latest bundled library chart:**
134134

135135
- `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not.
136-
- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).
136+
- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below.
137137

138-
`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved.
138+
`--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.
139139

140140
**Manage encrypted secrets in-place:**
141141

@@ -154,6 +154,10 @@ talm init --update --preset cozystack --force # non-interactive: auto-accept al
154154

155155
`--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`.
156156

157+
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.
158+
159+
`--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, and its `version` is restamped to the talm release you ran. 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. `image` goes back to the installer the preset ships (`v1.12.6` in talm v0.35.0), also without an error or a warning, and `talm upgrade` takes its target from `values.yaml` unless you pass `--image`: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned `image` back before that upgrade. Keep both files in git and diff them after every `--update`.
160+
157161
#### Chart Drift Detection (Talm v0.32+)
158162

159163
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:

‎content/en/docs/v1.3/install/kubernetes/talm.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e
132132
**Update an existing project to the latest bundled library chart:**
133133

134134
- `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not.
135-
- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).
135+
- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below.
136136

137-
`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved.
137+
`--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.
138138

139139
**Manage encrypted secrets in-place:**
140140

@@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p
151151
talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs
152152
```
153153

154+
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.
155+
156+
`--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, and its `version` is restamped to the talm release you ran. 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. `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. `image` goes back to the installer the preset ships (`v1.12.6` in talm v0.35.0), also without an error or a warning, and `talm upgrade` takes its target from `values.yaml` unless you pass `--image`: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned `image` back before that upgrade. Keep both files in git and diff them after every `--update`.
157+
154158
#### Encrypt / Decrypt Round-Trip
155159

156160
The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two:

‎content/en/docs/v1.4/install/kubernetes/talm.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e
132132
**Update an existing project to the latest bundled library chart:**
133133

134134
- `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not.
135-
- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).
135+
- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below.
136136

137-
`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved.
137+
`--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.
138138

139139
**Manage encrypted secrets in-place:**
140140

@@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p
151151
talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs
152152
```
153153

154+
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.
155+
156+
`--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, and its `version` is restamped to the talm release you ran. 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. `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. `image` goes back to the installer the preset ships (`v1.12.6` in talm v0.35.0), also without an error or a warning, and `talm upgrade` takes its target from `values.yaml` unless you pass `--image`: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned `image` back before that upgrade. Keep both files in git and diff them after every `--update`.
157+
154158
#### Encrypt / Decrypt Round-Trip
155159

156160
The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two:

‎content/en/docs/v1.5/install/kubernetes/talm.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e
132132
**Update an existing project to the latest bundled library chart:**
133133

134134
- `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not.
135-
- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).
135+
- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below.
136136

137-
`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved.
137+
`--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.
138138

139139
**Manage encrypted secrets in-place:**
140140

@@ -151,6 +151,10 @@ talm init --update --preset cozystack # interactive: prompts for each p
151151
talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs
152152
```
153153

154+
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.
155+
156+
`--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, and its `version` is restamped to the talm release you ran. 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. `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. `image` goes back to the installer the preset ships (`v1.12.6` in talm v0.35.0), also without an error or a warning, and `talm upgrade` takes its target from `values.yaml` unless you pass `--image`: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned `image` back before that upgrade. Keep both files in git and diff them after every `--update`.
157+
154158
#### Encrypt / Decrypt Round-Trip
155159

156160
The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two:

‎content/en/docs/v1.6/install/kubernetes/talm.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,9 +133,9 @@ When `--endpoints` is given exactly one value, init auto-derives `values.yaml::e
133133
**Update an existing project to the latest bundled library chart:**
134134

135135
- `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not.
136-
- `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).
136+
- `--force` - auto-accept every preset-template diff, including the `Chart.yaml` and `values.yaml` overwrites described below.
137137

138-
`--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved.
138+
`--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.
139139

140140
**Manage encrypted secrets in-place:**
141141

@@ -154,6 +154,10 @@ talm init --update --preset cozystack --force # non-interactive: auto-accept al
154154

155155
`--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`.
156156

157+
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.
158+
159+
`--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, and its `version` is restamped to the talm release you ran. 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. `image` goes back to the installer the preset ships (`v1.12.6` in talm v0.35.0), also without an error or a warning, and `talm upgrade` takes its target from `values.yaml` unless you pass `--image`: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned `image` back before that upgrade. Keep both files in git and diff them after every `--update`.
160+
157161
#### Chart Drift Detection (Talm v0.32+)
158162

159163
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:

0 commit comments

Comments
 (0)