Image support matrix

Kairos offers several pre-built images for user convenience based on popular Linux distributions such as openSUSE, Alpine Linux, and Ubuntu. The Kairos core team does its best to test these images, but those that are based on systemd (e.g. openSUSE, Ubuntu) are more thoroughly tested due to their homogenous settings. Support for other non-systemd based flavors (e.g. Alpine) may be limited due to team bandwidth. However, as Kairos is an open source community-driven project, we welcome any contributions, bug reports, and bug fixes. Check out our Contribution guidelines for more information.

In addition, tighter integration with systemd allows for several features that are only available with it, such as live layering.

These images are pushed to quay.io and are available for installation and upgrading. The installable mediums included in the releases are generated using the methods described in the automated installation reference, and the images can be used for upgrades as well.

Image flavors

Kairos release processes generates images based on official container images from popular Linux distributions. If you don’t see your preferred distribution, check if we are already planning support for it or create a new issue.

Below is a list of the container repositories for each flavor:

The various images are available with different tags in the form of:

quay.io/kairos/<flavor>:<flavor_release>-<variant>-<arch>-<device>-<version>

For example: quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1. More about Kairos naming conventions here.

Notes:

• The Core images do not include any Kubernetes engine and can be used as a base for customizations.
• The Standard images include k3s and the kairos provider, which enables Kubernetes deployments and optionally enables p2p.
• The -img repositories contain an img file which can be directly written to an SD card or USB drive for use with ARM devices.

export IMAGE=quay.io/kairos/@flavor:@flavorRelease-core-arm64-rpi4-v3.2.3-img
docker run -ti --rm -v $PWD:/image quay.io/luet/base util unpack "$IMAGE" /image

Building core and standard generic images

Unfortunately we don’t have the resources and capacity to build every possible artifact in our matrix. Thankfully, you can still build those images manually on your local machine, all you need is git, docker and earthly. Here’s an example how to build an Almalinux ARM generic image

git checkout https://github.com/kairos-io/kairos.git
cd kairos
earthly +all-arm-generic --FAMILY=@family --FLAVOR=@flavor --FLAVOR_RELEASE=@flavorRelease --BASE_IMAGE=@baseImage --VARIANT=core

Framework images

Kairos releases contains also the framework assets that can be used to build Kairos images from Scratch.

Framework images can be found in quay at: https://quay.io/repository/kairos/framework.

Each tag follow the convention: <version>[-fips].

Versioning policy

Kairos follows Semantic Versioning and our releases signal changes to Kairos components, rather than changes to the underlying OS and package versions. Flavors are pinned to specific upstream OS branches (e.g. opensuse to leap 15.4) and major version bumps will be reflected through new flavors in our build matrix or through specific releases to follow upstream with regard to minor version bumps (e.g. leap 15.3 and leap 15.4).

Here are some key points to note:

• We only support the latest release branch with patch releases.
• Patch releases (e.g. 1.1.x) follow a weekly release cadence, unless there are exceptions for highly impactful bugs in Kairos itself or at the OS layer (e.g. high-severity CVEs).
• Minor releases follow a monthly cadence and are expected to bring enhancements through planned releases.
• Major releases signal new advanced features or significant changes to the codebase. In-place upgrades from old to new major release branches are not always guaranteed, but we strive for compatibility across versions.

Release changelog

Our changelog is published as part of the release process and contains all the changes, highlights, and release notes that are relevant to the release. We strongly recommend checking the changelog for each release before upgrading or building a customized version of Kairos.

Release changelogs are available for Kairos core and for each component. Below is a list of the components that are part of a Kairos release and their respective release pages with changelogs.

Service Billing Of Materials (SBOM)

SBOM lists are regularly pushed via the CI as part of the Github releases assets. For instance,

https://github.com/kairos-io/kairos/releases/download/v3.2.3/kairos-@flavor-@flavorRelease-core-amd64-generic-v3.2.3-sbom.spdx.json

is the SBOM for the core @flavor image.

Image verification

Images signatures are pushed regularly for tagged releases. To verify images with cosign (install guide) for example, you can use the following command:

cosign verify-attestation \
        --type spdx quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3 \
        --certificate-identity "https://github.com/kairos-io/kairos/.github/workflows/release.yaml@refs/tags/v3.2.3" \
        --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

To see how to verify image attestation during upgrades with kyverno, see the documentation page.