Ready to launch your Kubernetes cluster with ease? With Kairos, deployment is a breeze! Simply download the pre-packaged artifacts, boot up on a VM or bare metal, and let Kairos handle the rest. Whether you’re a Linux or Windows user, our quickstart guide will have you up and running in no time. Kairos can build a Kubernetes cluster for you with just a few simple steps!
The goal of this quickstart is to help you quickly and easily deploy a Kubernetes cluster using Kairos releases. With Kairos, you can easily build a k3s cluster in a VM, or a baremetal using our pre-packaged artifacts, even if you don’t already have a cluster. This process can also be used on bare metal hosts with some configuration adjustments. Check out our documentation further for more detailed instructions and examples.
To create a Kubernetes cluster with Kairos, the only thing needed is one or more machines that will become the Kubernetes nodes. No previously existing clusters is needed.
Once the installation is complete, you can begin using your Kubernetes cluster.
- A VM (hypervisor) or a physical server (bare-metal) that boots ISOs
- A Linux or a Windows machine where to run the Kairos CLI (optional, we will see)
cloud-initconfiguration file (example below)
- At least 30+ Gb of available disk space.
- Visit the Kairos release page on GitHub
- Select the latest release and download the assets of your flavor. For example,
pick the kairos-opensuse-leap-15.5-standard-amd64-generic-v2.5.0-k3sv1.29.0+k3s1.iso
ISO file for the openSUSE based version, where
k3sv1.29.0+k3s1in the name is the
v2.5.0is the Kairos one to deploy on a VM.
- You can also use netboot to boot Kairos over the network
Core images in the ship without K3s and P2P full-mesh functionalities; they can be used as a generic installer to deploy container images.
Standard images ship with k3s and P2P full-mesh instead. But beware that these options need to be explicitly enabled. In follow-up releases, k3s-only artifacts will also be available.
See Image Matrix Support for additional supported images and kernels.
Checking artifacts signatures
NoteThis feature will be available in Kairos version
1.5.0 and in all future releases.
Our ISO releases have sha256 files to checksum the validity of the artifacts. At the same time, our sha256 files are signed automatically in the CI during the release workflow to verify that they haven’t been tampered with, adding an extra step to the supply chain.
It is recommended that before starting any installation the whole security chain is validated by verifying our sha256 signature and validating that the checksum matches with the download artifacts.
To validate the whole chain you would need:
sha256sumwhich is usually installed by default on most linux distributions.
cosignto verify the signatures of the sha256 file. You can install cosign via their installation docs
- ISO, sha256, certificate and signature files for the release/flavor that you want to verify. All the artifacts are available on the kairos release page
In this example we will use the
v2.5.0 version and
opensuse flavor and
leap-15.5 flavor release.
First we check that we have all needed files:
We first verify that the sha256 checksums haven’t been tampered with:
$ COSIGN_EXPERIMENTAL=1 cosign verify-blob --cert kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.pem --signature kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.sig kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256
tlog entry verified with uuid: 51ef927a43557386ad7912802607aa421566772524319703a99f8331f0bb778f index: 11977200
Once we see that
Verified OK we can be sure that the file hasn’t been tampered with, and we can continue verifying the iso checksum.
For an example of a failure validation see below:
$ COSIGN_EXPERIMENTAL=1 cosign verify-blob --enforce-sct --cert kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.pem --signature kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.sig kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.modified
Error: verifying blob [kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.modified]: invalid signature when validating ASN.1 encoded signature
main.go:62: error during command execution: verifying blob [kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256.modified]: invalid signature when validating ASN.1 encoded signature
COSIGN_EXPERIMENTAL=1 to verify the blob using the keyless method. That means that only ephemeral keys are created to sign, and it relays on using
OIDC Identity Tokens to authenticate so not even Kairos developers have access to the private keys and can modify an existing signature. All signatures are done
via the CI with no external access to the signing process. For more information about keyless signing please check the cosign docs
Now we can verify that the integrity of the ISO hasnt been compromise:
$ sha256sum -c kairos-opensuse-leap-15.5-core-amd64-generic-v2.5.0.iso.sha256
Once we reached this point, we can be sure that from the ISO hasn’t been tampered with since it was created by our release workflow.
Now that you have the ISO at hand, it’s time to boot!
Here are some additional helpful tips depending on the physical/virtual machine you’re using.
When deploying on a bare metal server, directly flash the image into a USB stick. There are multiple ways to do this:
From the command line using the
dd if=/path/to/iso of=/path/to/dev bs=4MB
From the GUI
For example using an application like balenaEtcher but can be any other application which allows you to write bootable USBs.
Make sure you have KVM enabled, this will improve the performance of your VM significantly!
virt-install --name my-first-kairos-vm \
--vcpus 1 \
--memory 1024 \
--cdrom /path/to/kairos-opensuse-leap-15.5-standard-amd64-generic-v2.5.0-k3sv1.29.0+k3s1.iso \
--disk size=30 \
--os-variant opensuse-factory \
After booting you’ll be greeted with a GRUB boot menu with multiple options. The option you choose will depend on how you plan to install Kairos:
- The first entry will boot into installation with a QR code or WebUI, which we’ll cover in the next step.
- The second entry will boot into Manual installation mode, where you can install Kairos manually using the console.
- The third boot option boots into Interactive installation mode, where you can use the terminal host to drive the installation and skip the Configuration and Provisioning step.
To begin the installation process, select the first entry and let the machine boot. Eventually, a QR code will be printed on the screen. Follow the next step in the documentation to complete the installation.
After booting up the ISO, the machine will wait for you to provide configuration details before continuing with the installation process. There are different ways to provide these details:
- Use the WebUI to continue the installation.
- Serve the configuration via QR code.
- Connect to the machine via SSH and start the installation process with a configuration file ( with
kairos-agent manual-install <config>).
- Use a datasource iso, or a generating a custom one
The configuration file is a YAML file with
cloud-init syntax and additional Kairos configuration details. In this example, we’ll configure the node as a single-node Kubernetes cluster using K3s. We’ll also set a default password for the Kairos user and define SSH keys.
Here’s an example configuration file that you can use as a starting point:
#cloud-config at the top is not a comment. Make sure to start your configuration file with it.
# Define the user accounts on the node.
- name: "kairos" # The username for the user.
passwd: "kairos" # The password for the user.
ssh_authorized_keys: # A list of SSH keys to add to the user's authorized keys.
- github:mudler # A key from the user's GitHub account.
- "ssh-rsa AAA..." # A raw SSH key.
# Enable K3s on the node.
enabled: true # Set to true to enable K3s.
Save this file as config.yaml and use it to start the installation process with kairos-agent manual-install config.yaml. This will configure the node as a single-node Kubernetes cluster and set the default password and SSH keys as specified in the configuration file.
users: This block defines the user accounts on the node. In this example, it creates a user named
kairoswith the password
kairosand adds two SSH keys to the user’s authorized keys.
k3s: This block enables K3s on the node.
- If you want to enable experimental P2P support, check out P2P installation
NoteSeveral configurations can be added at this stage. See the configuration reference for further reading.
NoteYou can find instructions showing how to use the Kairos CLI below. In case you prefer to install via SSH and log in to the box, see the Manual installation section or the Interactive installation section to perform the installation manually from the console.
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 release artifact:
curl -L https://github.com/kairos-io/provider-kairos/releases/download/v2.6.3/kairosctl-v2.6.3-linux-amd64.tar.gz -o - | tar -xvzf - -C .
# optionally, install the CLI locally
mv kairosctl /usr/local/bin/kairosctl
chmod +x /usr/local/bin/kairosctl
The CLI allows to register a node with a QR Code screenshot, an QR Code image, or an EdgeVPN token. During pairing, the configuration is sent over, and the node will continue the installation process.
In a terminal window from your desktop/workstation, run:
kairosctl register --reboot --device /dev/sda --config config.yaml
- By default, the CLI will automatically take a screenshot to get the QR code. Make sure it fits into the screen. Alternatively, an image path or an EdgeVPN token can be supplied via arguments (e.g.
kairosctl register /img/pathor
kairosctl register <EdgeVPN token>).
--rebootflag will make the node reboot automatically after the installation is completed.
--deviceflag determines the specific drive where Kairos will be installed. Replace
/dev/sdawith your drive. Any existing data will be overwritten, so please be cautious.
--configflag is used to specify the config file used by the installation process.
After a few minutes, the configuration is distributed to the node and the installation starts. At the end of the installation, the system is automatically rebooted.
Accessing the Node
After the boot process, the node starts and is loaded into the system. You should already have SSH connectivity when the console is available.
To access to the host, log in as
sudopermissions are configured for the Kairos user.
You will be greeted with a welcome message:
Welcome to Kairos!
Refer to https://kairos.io for documentation.
It can take a few moments to get the K3s server running. However, you 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)
Active: active (running) since Thu 2022-09-01 12:02:39 CEST; 4 days ago
Main PID: 1834 (k3s-server)
kubeconfig file is available at
/etc/rancher/k3s/k3s.yaml. Please refer to the K3s documentation.
There are other ways to install Kairos:
- Automated installation
- Manual login and installation
- Create decentralized clusters
- Take over installation
- Installation via network
- Raspberry Pi
- CAPI Lifecycle Management (TODO)
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.