Skip to content

docs(install/talos): document Talos / talosctl / Cozystack version pairing #484

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvaps merged 2 commits into from
Apr 12, 2026
Merged

docs(install/talos): document Talos / talosctl / Cozystack version pairing #484

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39f138e
docs(install/talos): document Talos / talosctl / Cozystack version pa…
lexfrei Apr 11, 2026
7328101
docs(install/talos): show boot-to-talos prompt with real v1.11.6 defa…
lexfrei Apr 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions content/en/docs/v1/install/talos/boot-to-talos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.11.6]: ghcr.io/cozystack/cozystack/talos:v1.12.6
Add networking configuration? [yes]:
Interface [eth0]:
IP address [10.0.2.15]:
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down