Welcome to the Kairos Documentation

Kairos is the open-source project that simplifies Edge, cloud, and bare metal OS lifecycle management. With a unified Cloud Native API, Kairos is community-driven, open source, and distro agnostic.

Our key features include:

  • Immutability: ensure your infrastructure stays consistent with atomic upgrades
  • Security: protect your cluster from vulnerabilities and attacks with a read-only system
  • Container-based: manage your nodes as apps in containers for maximum flexibility and portability
  • P2P Mesh: self-coordinated, automated, no interaction Kubernetes deployments with P2P
  • Meta-Distribution, distro agnostic

In this documentation, you will find everything you need to know about Kairos, from installation and configuration, to examples and advanced features.

To get started with Kairos, follow the instructions in the quickstart guide. Then, check out the examples to see how Kairos can be used in real-world scenarios.

For more information, please refer to this documentation. If you have any questions or feedback, feel free to open an issue or join our community forum.

What is Kairos ?

Kairos is a cloud-native meta-Linux distribution that runs on Kubernetes and brings the power of the public cloud to your on-premises environment. With Kairos, you can build your own cloud with complete control and no vendor lock-in.

Here are a few reasons why you should try Kairos:

  • Build your own cloud on-premises with complete control and no vendor lock-in
  • Provision nodes with your own image or use Kairos releases for added flexibility
  • Use Kairos for a wide range of use cases, from Kubernetes applications to appliances and more
  • Simple and streamlined day-2 operations (e.g. node upgrades)

What I can do with it ?

With Kairos, you can easily spin up a Kubernetes cluster with the Linux distribution of your choice, and manage the entire cluster lifecycle with Kubernetes. Try Kairos today and experience the benefits of a unified, cloud-native approach to OS management.

With Kairos, you can:

  • Spin up a Kubernetes cluster with any Linux distribution in just a few clicks
  • Create an immutable infrastructure that stays consistent and free of drift with atomic upgrades
  • Manage your cluster’s entire lifecycle with Kubernetes, from building to upgrading
  • Automatically create multi-node, single clusters that spans across regions for maximum flexibility and scalability

Try Kairos today and experience the benefits of a unified, cloud-native approach to OS management. Say goodbye to the hassle of managing multiple systems, and hello to a more streamlined and efficient way of working.


  • Easily create multi-node Kubernetes clusters with K3s, and enjoy all of K3s’s features
  • Upgrade manually via CLI or with Kubernetes, and use container registries for distribution upgrades
  • Enjoy the benefits of an immutable distribution that stays configured to your needs
  • Configure nodes with a single cloud-init config file for added simplicity
  • Upgrade even in airgap environments with in-cluster container registries
  • Extend your image at runtime or build time with Kubernetes Native APIs
  • Coming soon: CAPI support with full device lifecycle management and more
  • Create private virtual network segments with a full-mesh P2P hybrid VPN network that can stretch up to 10000 km

More than a Linux distribution

Kairos is more than just an ISO, qcow2, or Netboot artifact. It allows you to turn any Linux distribution into a uniform and compliant distro with an immutable design. This means that any distro “converted” with Kairos will share the same common feature set and can be managed in the same way using Kubernetes Native API components. Kairos treats all OSes homogeneously and upgrades are distributed via container registries. Installations mediums and other assets required for booting bare metal or edge devices are built dynamically by Kairos’ Kubernetes Native API components.



The Kairos ultimate goal is to bridge the gap between Cloud and Edge by creating a smooth user experience. There are several areas in the ecosystem that can be improved for edge deployments to make it in pair with the cloud.

The Kairos project encompasses all the tools and architectural pieces needed to fill those gaps. This spans between providing Kubernetes Native API components to assemble OSes, deliver upgrades, and control nodes after deployment.

Kairos is distro-agnostic, and embraces openness: The user can provide their own underlying base image, and Kairos onboards it and takes it over to make it Cloud Native, immutable that plugs into an already rich ecosystem by leveraging containers as distribution medium.


Kairos is an open source project, and any contribution is more than welcome! The project is big and narrows to various degrees of complexity and problem space. Feel free to join our chat, discuss in our forums and join us in the Office hours. Check out the contribution guidelines to see how to get started and our governance.

We have an open roadmap, so you can always have a look on what’s going on, and actively contribute to it.

Useful links:


You can find us at:

Project Office Hours

Project Office Hours is an opportunity for attendees to meet the maintainers of the project, learn more about the project, ask questions, learn about new features and upcoming updates.

Office hours are happening weekly on Wednesday - 5:30 – 6:00pm CEST. Meeting link

Besides, we have monthly meetup to participate actively into the roadmap planning and presentation which takes part during the office hours:

Roadmap planning

We will discuss on agenda items and groom issues, where we plan where they fall into the release timeline.

Occurring: Monthly on the first Wednesday - 5:30 – 6:30pm CEST.

Roadmap presentation

We will discuss the items of the roadmaps and the expected features on the next releases

Occurring: Monthly on the second Wednesday - 5:30pm CEST.


There are other projects that are similar to Kairos which are great and worth to mention, and actually Kairos took to some degree inspiration from. However, Kairos have different goals and takes completely unique approaches to the underlying system, upgrade, and node lifecycle management.


Building Kairos

Requirements: Needs only Docker.

Run the following command to produce a Docker image along with a working ISO:

earthly +iso \
  --FAMILY=rhel \
  --FLAVOR=fedora \
  --BASE_IMAGE=fedora:38 \
  --MODEL=generic \

What’s next?

See the quickstart to install Kairos on a VM and create a Kubernetes cluster!

Artifact Naming Convention

Detailed information about how we name our artifacts including repositories.


Kairos internal architecture

Development notes

Guidelines when developing Kairos


Manual installation

Install Kairos manually

QR Code

Use the QR code displayed at boot to drive the installation

Upgrading from Kubernetes


Use the WebUI at boot to drive the installation

Pushing configuration to a node after installation

Configuring partitions

Configuring wifi via cloud-config

Multi Node k3s cluster

This section describe examples on how to deploy Kairos with k3s as a multi-node cluster

Single Node k3s cluster

This section describe examples on how to deploy Kairos with k3s as a single-node cluster

Private registries authentication



Welcome to the Kairos configuration reference page. This page provides details on the fields available in the YAML file used for installing Kairos, a Linux distribution focused on running Kubernetes. This file, written in cloud-config format, allows you to enable Kairos features, configure k3s, and set various other options.

Container based


Install Kairos interactively


Customizing the system image

Getting Started

Getting started with Kairos


Kairos Installation reference

SecureBoot support


Install Kairos automatically, with zero touch provisioning

Cloud init based


High Availability K3s deployments

This section contains instructions how to deploy Kairos with a High Available control-plane for K3s



Debugging station

Debugging station


Nvidia AGX Orin

Install Kairos on Nvidia AGX Orin


Install Kairos on RaspberryPi 3 and 4

Reset a node

How to Create an Airgap K3s Installation with Kairos

This section describe examples on how to use AuroraBoot and Kairos bundles to create ISOs for airgapped installs



This section describe examples on how to use a Kairos bundle to deploy MetalLB on top of K3s

Live layering


This section describe examples on how to deploy Kairos with k3s and LocalAI


This section describe examples on how to deploy Kairos with k3s and MetalLB

Using Kairos Core Images as an Installer

Core images serve as the foundation for creating downstream images or as an installer for deploying other images during the installation process. In this guide, we’ll take a closer look at using Kairos core images as an installer to deploy other container images.

P2P Network

How Kairos leverage Peer-to-peer (P2P) to self-coordinate clusters at the edge.

Booting Kairos on Nvidia Jetson ARM

This page contains a reference on how to run Kairos on Nvidia Jetson ARM

Image support matrix


Advanced settings

Build Kairos appliances

Build Kairos from scratch

This article shows how to bring your own image with Kairos, and build a Kairos derivative from scratch using base container images from popular distributions such as Ubuntu, Fedora, openSUSE, etc.


Bundles are a powerful feature of Kairos that allow you to customize and configure your operating system. This section explains how to use and build custom bundles.

Encrypting User Data with Kairos

This section describes how to encrypt partition with LUKS in Kairos.


This section contains various examples, how-to and tutorial to use Kairos

Network booting

Install Kairos from network

Intel Open AMT Registration

This bundle configures Intel AMT devices during Kairos installation.

P2P multi-node cluster with AuroraBoot

Full end to end example to bootstrap a self-coordinated cluster with Kairos and AuroraBoot

Configuring Automatic High Availability in Kairos

Kairos makes it easy to configure automatic High Availability (HA) in your cluster by using cloud-config. With just a few simple steps, you can have a fully-functioning HA setup in your cluster.

Deploying a High-Availability K3s Cluster with KubeVIP

This guide walks through the process of deploying a highly-available, P2P self-coordinated k3s cluster with KubeVIP, which provides a high available Elastic IP for the control plane.

P2P multi-node cluster

Install Kairos with p2p support, on a multi-node cluster

P2P single-node cluster

This documentation page provides instructions on how to install Kairos with P2P support on a single-node cluster

P2P support

Install Kairos with p2p support


Trusted Boot Architecture

Trusted Boot Installations

Trusted Boot Upgrades


Recovery mode




Automatically provision machines with Kairos and AuroraBoot.

Entangle CRDs

Inter-connecting Kubernetes clusters without the need of exposing any service to the public via E2E P2P encrypted networks.


Confidential computing setup


Presentation Slides, Videos and other media on Kairos


Known Issues

Last modified March 19, 2024: Add v3.0.1 branch (1fbe732)