Detailed information about how we name our artifacts including repositories.
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.
NoteYou can also find some good resources on the Media Section
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.
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:
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.
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.
Requirements: Needs only Docker.
Run the following command to produce a Docker image along with a working ISO:
earthly +iso \
See the quickstart to install Kairos on a VM and create a Kubernetes cluster!
Kairos internal architecture
Guidelines when developing Kairos
Install Kairos manually
Use the QR code displayed at boot to drive the installation
Use the WebUI at boot to drive the installation
This section describe examples on how to deploy Kairos with k3s as a multi-node cluster
This section describe examples on how to deploy Kairos with k3s as a single-node cluster
Install Kairos interactively
Getting started with Kairos
Kairos Installation reference
Install Kairos automatically, with zero touch provisioning
This section contains instructions how to deploy Kairos with a High Available control-plane for K3s
Install Kairos on Nvidia AGX Orin
Install Kairos on RaspberryPi 3 and 4
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
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
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.
How Kairos leverage Peer-to-peer (P2P) to self-coordinate clusters at the edge.
This page contains a reference on how to run Kairos on Nvidia Jetson ARM
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.
This section describes how to encrypt partition with LUKS in Kairos.
This section contains various examples, how-to and tutorial to use Kairos
Install Kairos from network
This bundle configures Intel AMT devices during Kairos installation.
Full end to end example to bootstrap a self-coordinated cluster with Kairos and AuroraBoot
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.
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.
Install Kairos with p2p support, on a multi-node cluster
This documentation page provides instructions on how to install Kairos with P2P support on a single-node cluster
Install Kairos with p2p support
Automatically provision machines with Kairos and AuroraBoot.
Inter-connecting Kubernetes clusters without the need of exposing any service to the public via E2E P2P encrypted networks.
Presentation Slides, Videos and other media on Kairos
Was this page helpful?
Awesome! Glad to hear it! Please tell us how we can improve.
Oh snap! Sorry to hear that. Please tell us how we can improve.