Skip to content

Commit 95123d6

Browse files
authored
docs(install/talos): document Talos / talosctl / Cozystack version pairing (#484)
## What Adds a new *Version Compatibility* section to `content/en/docs/v1/install/talos/boot-to-talos.md` spelling out which Talos image the reader has to feed to `boot-to-talos` for a given Cozystack release, how `talosctl` has to line up, and why the `boot-to-talos` interactive default is *not* the right answer on its own. Also refreshes the console-session example on the same page (`v1.10.5` → `v1.12.6`) so it matches the pinned Talos version the rest of the v1 docs and the Cozystack v1.2.x release profile use. ## Why Fresh-install users in the community chat keep hitting the same version mismatch: - `boot-to-talos` v0.7.1 (the latest release) hard-codes its default installer image to `ghcr.io/cozystack/cozystack/talos:v1.11.6` in `cmd/boot-to-talos/main.go`. - Cozystack v1.2.x pins Talos **v1.12.6** in `packages/core/talos/images/talos/profiles/installer.yaml`, and Talm / Helm templates target v1.12. - `talosctl` is downloaded separately and defaults to whatever `latest` is on siderolabs/talos (`v1.12.6` today). If the reader follows the boot-to-talos prompts and accepts the suggested default, they get a Talos v1.11 node under a Cozystack installer that expects v1.12, and the bootstrap fails in obscure ways (schedule errors, Talm template failures, nested-CRD mismatches). The fix is trivial — type in the right image — but it is not documented anywhere the reader would find it before running the command. The new section: - Lists the three moving parts (Talos / talosctl / Cozystack) in a short compatibility table. - Names the concrete pair for Cozystack v1.2.x (Talos `v1.12.6` + `talosctl` v1.12.x) and links to the profile file in `cozystack/cozystack` so a reader on a different release can look up the same for themselves. - Adds a warning callout that explains the boot-to-talos default is unrelated to the Cozystack release and links directly to the `main.go` line where the default lives. ## Verification - Pinned Talos version confirmed against `packages/core/talos/images/talos/profiles/installer.yaml` in `cozystack/cozystack` at tag `release-1.2.1` (`version: v1.12.6`, `baseInstaller.imageRef: ghcr.io/siderolabs/installer:v1.12.6`). - `boot-to-talos` default verified via `gh search code --repo cozystack/boot-to-talos "v1.11"`, which points at `cmd/boot-to-talos/main.go` defaulting to `ghcr.io/cozystack/cozystack/talos:v1.11.6`. - `ghcr.io/cozystack/cozystack/talos:v1.12.6` existence verified via the GHCR package API. - `hugo` builds cleanly; the new section and refreshed example render correctly. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated boot-to-talos documentation with version compatibility guidance for Cozystack v1.2.x (Talos v1.12.6). * Added warning about potential version mismatches when using default Talos installer images. * Updated example logs and defaults to reflect current versions. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents 752cd40 + 7328101 commit 95123d6

1 file changed

Lines changed: 30 additions & 5 deletions

File tree

content/en/docs/v1/install/talos/boot-to-talos.md

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,31 @@ It works entirely from userspace and has no external dependencies except the Tal
1414

1515
Note that Cozystack provides its own Talos builds, which are tested and optimized for running a Cozystack cluster.
1616

17+
## Version Compatibility
18+
19+
Three versions need to line up when you install Cozystack on Talos:
20+
21+
| Component | Where it comes from | Must match |
22+
| --- | --- | --- |
23+
| **Talos** on the node | `-image` flag passed to `boot-to-talos` | the Talos version that ships with the Cozystack release you are installing |
24+
| **`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 |
25+
| **Cozystack** | `--version` flag passed to `helm upgrade --install cozy-installer` | — (the anchor; everything else follows) |
26+
27+
For **Cozystack v1.2.x** the pinned Talos version is **v1.12.6**
28+
([`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)).
29+
Use `ghcr.io/cozystack/cozystack/talos:v1.12.6` as the `boot-to-talos` image and download `talosctl` v1.12.x.
30+
31+
{{% alert color="warning" %}}
32+
`boot-to-talos` v0.7.x carries its own hardcoded default image
33+
(`ghcr.io/cozystack/cozystack/talos:v1.11.6` as of v0.7.1, see
34+
[`cmd/boot-to-talos/main.go`](https://github.com/cozystack/boot-to-talos/blob/v0.7.1/cmd/boot-to-talos/main.go)).
35+
If you let the interactive prompt fall through to that default on a cluster
36+
you intend to run Cozystack v1.2.x, you will end up with a Talos v1.11 node
37+
while the Cozystack installer and Talm templates target Talos v1.12 — you
38+
will hit a mismatch at bootstrap time. Always type in the image matching
39+
your target Cozystack release (or pass `-image` on the command line).
40+
{{% /alert %}}
41+
1742
## Modes
1843

1944
`boot-to-talos` supports two installation modes:
@@ -53,7 +78,7 @@ Mode:
5378
2. install – prepare the environment, run the Talos installer, and then overwrite the system disk with the installed image.
5479
Mode [1]: 2
5580
Target disk [/dev/sda]:
56-
Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.10.5]:
81+
Talos installer image [ghcr.io/cozystack/cozystack/talos:v1.11.6]: ghcr.io/cozystack/cozystack/talos:v1.12.6
5782
Add networking configuration? [yes]:
5883
Interface [eth0]:
5984
IP address [10.0.2.15]:
@@ -62,7 +87,7 @@ Gateway (or 'none') [10.0.2.2]:
6287
Configure serial console? (or 'no') [ttyS0]:
6388
6489
Summary:
65-
Image: ghcr.io/cozystack/cozystack/talos:v1.10.5
90+
Image: ghcr.io/cozystack/cozystack/talos:v1.12.6
6691
Disk: /dev/sda
6792
Extra kernel args: ip=10.0.2.15::10.0.2.2:255.255.255.0::eth0::::: console=ttyS0
6893
@@ -71,12 +96,12 @@ WARNING: ALL DATA ON /dev/sda WILL BE ERASED!
7196
Continue? [yes]:
7297
7398
2025/08/03 00:11:03 created temporary directory /tmp/installer-3221603450
74-
2025/08/03 00:11:03 pulling image ghcr.io/cozystack/cozystack/talos:v1.10.5
99+
2025/08/03 00:11:03 pulling image ghcr.io/cozystack/cozystack/talos:v1.12.6
75100
2025/08/03 00:11:03 extracting image layers
76101
2025/08/03 00:11:07 creating raw disk /tmp/installer-3221603450/image.raw (2 GiB)
77102
2025/08/03 00:11:07 attached /tmp/installer-3221603450/image.raw to /dev/loop0
78103
2025/08/03 00:11:07 starting Talos installer
79-
2025/08/03 00:11:07 running Talos installer v1.10.5
104+
2025/08/03 00:11:07 running Talos installer v1.12.6
80105
2025/08/03 00:11:07 WARNING: config validation:
81106
2025/08/03 00:11:07 use "worker" instead of "" for machine type
82107
2025/08/03 00:11:07 created EFI (C12A7328-F81F-11D2-BA4B-00A0C93EC93B) size 104857600 bytes
@@ -91,7 +116,7 @@ Continue? [yes]:
91116
2025/08/03 00:11:07 copying from io reader to /boot/A/initramfs.xz
92117
2025/08/03 00:11:08 writing /boot/grub/grub.cfg to disk
93118
2025/08/03 00:11:08 executing: grub-install --boot-directory=/boot --removable --efi-directory=/boot/EFI /dev/loop0
94-
2025/08/03 00:11:08 installation of v1.10.5 complete
119+
2025/08/03 00:11:08 installation of v1.12.6 complete
95120
2025/08/03 00:11:08 Talos installer finished successfully
96121
2025/08/03 00:11:08 remounting all filesystems read-only
97122
2025/08/03 00:11:08 copy /tmp/installer-3221603450/image.raw → /dev/sda

0 commit comments

Comments
 (0)