The Kairos releases ships for user convenience a set of artifacts that can be used to install kairos on a node. However, Kairos Kubernetes Native components allows the creation of these artifacts inside Kubernetes from a set of input images.
In the quickstart below we will use the artifacts generated by the kairos releases as we assume we don’t have any prior Kubernetes cluster available.
Most of the operations are completely automated, so there is little interaction needed with the Kubernetes components.
Installation can be also completely driven by the Kubernetes Native components if you have already a Kubernetes cluster to manage installations, with zero touch configuration. See the CRD quickstart (WIP).
The goal of this quickstart is to install kairos on a node and create a single-node Kubernetes cluster with k3s.
To simplify, we will install kairos inside a VM, however, your mileage and configuration may vary based on your setup, see the documentation for a more exhaustive list of examples.
Kairos can be used to turn any distro in an immutable system, however, for user convenience there are several artifacts published as part of the releases to get started.
You can find the latest releases in the release page over Github. For instance, if we would like to pick the alpine based version, we would download the
kairos-alpine-v0.57.0-k3sv1.21.14+k3s1.iso ISO file, where
v1.21.14+k3s1 in the name is the
k3s version and
v0.57.0 is the kairos one.
The releases in the kairos-io/kairos repository are the
kairos core images that ship without
p2p full-mesh functionalities, however further extensions can be installed dynamically in runtime by using the kairos bundles mechanism.
The releases in kairos-io/provider-kairos instead ships
p2p full-mesh support that needs to be explictly enabled. In follow-up releases there will be available also k3s-only artifacts.
Download the ISO, and boot it up in to the hypervisor of your choice. If it’s a baremetal, you can flash the image directly into an usb stick with dd:
dd if=/path/to/iso of=/path/to/dev bs=4MB
or just use Etcher.
You should be greeted with a GRUB boot menu: There are several entries, depending on how you plan to install kairos. Let’s pick the first entry, or wait the default timeout. The machine will boot, and eventually a QR code will be printed out of the screen:
At this stage the machine is waiting for the configuration to continue futher with the installation process. Configuration can be either served via QR code, or manually via logging into the box and starting the installation process with a config file. The config file is a YAML file mixed with
cloud-init syntax and the config of
In this example we will configure the node as a single-node kubernetes cluster, so we enable
k3s, and we set a default password for the
kairos user to later access to the box, alongside with some ssh keys:
#node-config stages: initramfs: - name: "User settings" hostname: "hostname.domain.tld" authorized_keys: kairos: - "ssh-rsa AAA..." - "github:mudler" users: kairos: passwd: "kairos" dns: path: /etc/resolv.conf nameservers: - 126.96.36.199 k3s: enabled: true
Save the config file as
config.yaml as we will use it later in the process.
stages.initramfsblock will configure the
kairosuser (default) with the
kairospassword. Note, the
kairosuser is already configured with sudo.
authorized_keyscan be used to add additional keys to the user in order to SSH into
hostnamesets the machine hostname
dnssets the DNS for the machine
Several configuration can be added at this stage. See the configuration reference for further reading.
Below there are instruction using the
kairos-cli which works only on Linux.
To trigger the installation process via QR code you need to use the
kairos-cli, the cli is currently available only for Linux and Windows. It can be downloaded from the releases artifact:
curl -L https://github.com/kairos-io/provider-kairos/releases/download/v0.57.0/kairos-cli-v0.57.0-Linux-x86_64.tar.gz -o - | tar -xvzf - -C .
The CLI allows to register a node with a screenshot, an image, or a token. During pairing the configuration is sent over and the node will continue the installation process.
In a terminal in your desktop/workstation, run:
kairos register --reboot --device /dev/sda --config config.yaml
kairos register /img/pathor
kairos register <token>)
--rebootflag will make the node reboot automatically after the installation is completed
--deviceflag will instruct to install kairos in the specified drive, replace
/dev/sdawith your drive. It will take over and overwrite any content, please be cautious.
--configflag is used to specify the config file to drive the installation
Wait now for few minutes for the config to propagate to the node, the installation should start then and automatically reboot afterward.
After boot the node will start and load into the system. When the console is available we should be already able to SSH.
To access to the host, login as
sudois configured for the
You should be greeted with a welcome message:
Welcome to kairos! Refer to https://kairos.io for documentation. kairos@kairos:~>
At this point, it can take few moments to get the k3s server running, but eventually we should be able to inspect the service and see k3s running, for example with systemd-based flavors:
$ sudo systemctl status k3s ● k3s.service - Lightweight Kubernetes Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: disabled) Drop-In: /etc/systemd/system/k3s.service.d └─override.conf Active: active (running) since Thu 2022-09-01 12:02:39 CEST; 4 days ago Docs: https://k3s.io Main PID: 1834 (k3s-server) Tasks: 220
k3s kubeconfig file is available at
/etc/rancher/k3s/k3s.yaml. Please refer to the k3s documentation.
There are other ways to install kairos: