From 39f138ea8f699ab2cb22330c6328425c80f9f43a Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Sun, 12 Apr 2026 01:09:11 +0300 Subject: [PATCH 1/2] docs(install/talos): document Talos / talosctl / Cozystack version pairing New users repeatedly hit a version mismatch when installing Cozystack via boot-to-talos in the Russian community chat: boot-to-talos v0.7.1 ships with a hardcoded default image of ghcr.io/cozystack/cozystack/talos:v1.11.6, while Cozystack v1.2.x actually pins Talos v1.12.6 in packages/core/talos/images/talos/ profiles/installer.yaml. If the user accepts the interactive default they get a Talos v1.11 node underneath a Cozystack installer that expects Talos v1.12, and the bootstrap fails in obscure ways. Add a Version Compatibility section to the boot-to-talos install guide that spells out: - the three things that need to line up (Talos image, talosctl, Cozystack release), - the specific pinned Talos version for Cozystack v1.2.x (v1.12.6), with a link to the profile file upstream, - a warning callout that boot-to-talos keeps its own default image separate from whatever Cozystack release the reader is installing, with a link to the exact line in cmd/boot-to-talos/main.go. Also refresh the interactive session example further down the page so it shows v1.12.6 instead of the stale v1.10.5, matching the rest of the v1 docs. Assisted-By: Claude Signed-off-by: Aleksei Sviridkin --- .../en/docs/v1/install/talos/boot-to-talos.md | 35 ++++++++++++++++--- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/content/en/docs/v1/install/talos/boot-to-talos.md b/content/en/docs/v1/install/talos/boot-to-talos.md index 49727c11..6f3cbbbc 100644 --- a/content/en/docs/v1/install/talos/boot-to-talos.md +++ b/content/en/docs/v1/install/talos/boot-to-talos.md @@ -14,6 +14,31 @@ It works entirely from userspace and has no external dependencies except the Tal Note that Cozystack provides its own Talos builds, which are tested and optimized for running a Cozystack cluster. +## Version Compatibility + +Three versions need to line up when you install Cozystack on Talos: + +| Component | Where it comes from | Must match | +| --- | --- | --- | +| **Talos** on the node | `-image` flag passed to `boot-to-talos` | the Talos version that ships with the Cozystack release you are installing | +| **`talosctl`** on your workstation | downloaded separately from [siderolabs/talos releases](https://github.com/siderolabs/talos/releases) | the major.minor of the Talos version you wrote to the node | +| **Cozystack** | `--version` flag passed to `helm upgrade --install cozy-installer` | — (the anchor; everything else follows) | + +For **Cozystack v1.2.x** the pinned Talos version is **v1.12.6** +([`packages/core/talos/images/talos/profiles/installer.yaml`](https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/core/talos/images/talos/profiles/installer.yaml)). +Use `ghcr.io/cozystack/cozystack/talos:v1.12.6` as the `boot-to-talos` image and download `talosctl` v1.12.x. + +{{% alert color="warning" %}} +`boot-to-talos` v0.7.x carries its own hardcoded default image +(`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see +[`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)). +If you let the interactive prompt fall through to that default on a cluster +you intend to run Cozystack v1.2.x, you will end up with a Talos v1.11 node +while the Cozystack installer and Talm templates target Talos v1.12 — you +will hit a mismatch at bootstrap time. Always type in the image matching +your target Cozystack release (or pass `-image` on the command line). +{{% /alert %}} + ## Modes `boot-to-talos` supports two installation modes: @@ -53,7 +78,7 @@ Mode: 2. install – prepare the environment, run the Talos installer, and then overwrite the system disk with the installed image. Mode [1]: 2 Target disk [/dev/sda]: -Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.10.5]: +Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.12.6]: Add networking configuration? [yes]: Interface [eth0]: IP address [10.0.2.15]: @@ -62,7 +87,7 @@ Gateway (or 'none') [10.0.2.2]: Configure serial console? (or 'no') [ttyS0]: Summary: - Image: ghcr.io/cozystack/cozystack/talos:v1.10.5 + Image: ghcr.io/cozystack/cozystack/talos:v1.12.6 Disk: /dev/sda Extra kernel args: ip=10.0.2.15::10.0.2.2:255.255.255.0::eth0::::: console=ttyS0 @@ -71,12 +96,12 @@ WARNING: ALL DATA ON /dev/sda WILL BE ERASED! Continue? [yes]: 2025/08/03 00:11:03 created temporary directory /tmp/installer-3221603450 -2025/08/03 00:11:03 pulling image ghcr.io/cozystack/cozystack/talos:v1.10.5 +2025/08/03 00:11:03 pulling image ghcr.io/cozystack/cozystack/talos:v1.12.6 2025/08/03 00:11:03 extracting image layers 2025/08/03 00:11:07 creating raw disk /tmp/installer-3221603450/image.raw (2 GiB) 2025/08/03 00:11:07 attached /tmp/installer-3221603450/image.raw to /dev/loop0 2025/08/03 00:11:07 starting Talos installer -2025/08/03 00:11:07 running Talos installer v1.10.5 +2025/08/03 00:11:07 running Talos installer v1.12.6 2025/08/03 00:11:07 WARNING: config validation: 2025/08/03 00:11:07 use "worker" instead of "" for machine type 2025/08/03 00:11:07 created EFI (C12A7328-F81F-11D2-BA4B-00A0C93EC93B) size 104857600 bytes @@ -91,7 +116,7 @@ Continue? [yes]: 2025/08/03 00:11:07 copying from io reader to /boot/A/initramfs.xz 2025/08/03 00:11:08 writing /boot/grub/grub.cfg to disk 2025/08/03 00:11:08 executing: grub-install --boot-directory=/boot --removable --efi-directory=/boot/EFI /dev/loop0 -2025/08/03 00:11:08 installation of v1.10.5 complete +2025/08/03 00:11:08 installation of v1.12.6 complete 2025/08/03 00:11:08 Talos installer finished successfully 2025/08/03 00:11:08 remounting all filesystems read-only 2025/08/03 00:11:08 copy /tmp/installer-3221603450/image.raw → /dev/sda From 7328101ddf29814fb350120dd846ae67a08ca9d6 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Sun, 12 Apr 2026 01:25:32 +0300 Subject: [PATCH 2/2] docs(install/talos): show boot-to-talos prompt with real v1.11.6 default and explicit v1.12.6 override Review comments on #484 from gemini-code-assist and coderabbitai flagged the same mismatch: the interactive session example showed v1.12.6 inside the prompt brackets (implying that is what pressing Enter would give you), but the warning block above it says the real boot-to-talos v0.7.x default is v1.11.6. Those two statements contradicted each other. Fix: show the actual default the tool prints in brackets (v1.11.6) followed by the explicit user override (v1.12.6) on the same line. This is what a reader would actually see and type, and it reinforces the version-compatibility warning instead of contradicting it. Assisted-By: Claude Signed-off-by: Aleksei Sviridkin --- content/en/docs/v1/install/talos/boot-to-talos.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v1/install/talos/boot-to-talos.md b/content/en/docs/v1/install/talos/boot-to-talos.md index 6f3cbbbc..8c5f5a96 100644 --- a/content/en/docs/v1/install/talos/boot-to-talos.md +++ b/content/en/docs/v1/install/talos/boot-to-talos.md @@ -78,7 +78,7 @@ Mode: 2. install – prepare the environment, run the Talos installer, and then overwrite the system disk with the installed image. Mode [1]: 2 Target disk [/dev/sda]: -Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.12.6]: +Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.11.6]: ghcr.io/cozystack/cozystack/talos:v1.12.6 Add networking configuration? [yes]: Interface [eth0]: IP address [10.0.2.15]: