Skip to content

Commit c2659c1

Browse files
committed
docs(readme): document talosVersion compatibility with maintenance Talos
The talosVersion / --talos-version setting was only described as an output-format selector. It is also (and more critically) the contract that decides which fields machinery injects into the generated config, which must match what the maintenance Talos parser on the node knows. A user who sets it from install.image (a different artifact) lands on 'unknown keys found during decoding: machine.install.grubUseUKICmdline' and has no doc-side guidance — see #132 and the reproduction in cozystack/cozystack#2442. Add a short paragraph that names the failure mode, points at the pre-flight warning the apply path now prints, and tells the user the two ways out (reboot into a maintenance image matching the contract, or lower the contract). Keep it next to the existing output-format note where readers are already looking at this setting. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 2080a8d commit c2659c1

1 file changed

Lines changed: 2 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,8 @@ cluster:
150150
> For Talos < v1.12, the output is a single YAML document with `machine.network` and `machine.registries` sections (as shown above).
151151
> For Talos >= v1.12, the output uses the multi-document format with separate typed documents instead of the deprecated monolithic fields. `HostnameConfig`, `ResolverConfig` and a network interface document (`LinkConfig`, `BondConfig`, or `VLANConfig` — depending on topology) are always emitted; `Layer2VIPConfig` appears on controlplane nodes when `floatingIP` is set; `RegistryMirrorConfig` is emitted only by the cozystack chart.
152152

153+
> **Version compatibility (`templateOptions.talosVersion` / `--talos-version`).** This setting must match the **Talos version actually running on the target node** — i.e. the maintenance ISO/PXE the node booted from for `apply -i`, or the installed Talos for an authenticated apply. It is **not** the same as `install.image`, which only controls what gets written to disk after a successful apply. When the configured contract is newer than the running binary, machinery injects fields (e.g. `machine.install.grubUseUKICmdline` from v1.12) that the running parser does not know, and the apply fails on the node side with `failed to parse config: unknown keys found during decoding: ...`. `talm apply` runs a best-effort pre-flight check against the running version and prints a `warning: pre-flight: ...` line with a hint when it detects this mismatch; if the warning is missed, the same hint is appended to the apply error. Either reboot the node into a maintenance image that matches the configured contract, or lower `templateOptions.talosVersion` / `--talos-version` to match what is running.
154+
153155
Apply config:
154156
```bash
155157
talm apply -f nodes/node1.yaml -i

0 commit comments

Comments
 (0)