Kairos

https://kairos.io/docs/v4.1.0
Admin
Kairos is an open-source project that simplifies Edge, cloud, and bare metal OS lifecycle management...
Tokens:141,517
Snippets:1,438
Trust Score:8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Full Example with Auto Installation

Source: https://kairos.io/docs/v4.1.0/installation/p2p

A comprehensive configuration example including automatic installation settings and P2P for cluster bootstrapping.

```yaml
#cloud-config

install:
  auto: true
  device: "auto"
  reboot: true
  
hostname: "kubevip-{{ trunc 4 .MachineID }}"
users:
- name: "kairos"
  passwd: "kairos"
  ssh_authorized_keys:
  - github:mudler
  

```

--------------------------------

### Example: Start Agent Configuration

Source: https://kairos.io/docs/v4.1.0/architecture/cloud-init

Configuration snippet for 'Start agent' service, including conditional execution and file deployment.

```yaml
name: "Start agent"  

stages:  

  boot:  

    - if: '[ ! -f "/run/cos/recovery_mode" ]'  

      only_service_manager: "systemd"  

      files:  

        - path: /etc/systemd/system/kairos-agent.service  

...  


```

--------------------------------

### Example lsblk Output After Installation

Source: https://kairos.io/docs/v4.1.0/advanced/multi-disk-dynamic-partitioning

This output demonstrates the expected disk and partition structure on the installed system, showing labeled partitions for boot, recovery, state, and persistent storage.

```text
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS  
vda    253:0    0   20G  0 disk  
├─vda1 253:1    0   64M  0 part               ← COS_GRUB  (EFI)  
└─vda2 253:2    0 19.9G  0 part /oem          ← COS_OEM  
vdb    253:16   0   30G  0 disk  
├─vdb1 253:17   0    4G  0 part               ← COS_RECOVERY  
├─vdb2 253:18   0    8G  0 part /run/initramfs/cos-state  ← COS_STATE  
└─vdb3 253:19   0   18G  0 part /var/lib/...  ← COS_PERSISTENT  
```

--------------------------------

### Example: Start Recovery Configuration

Source: https://kairos.io/docs/v4.1.0/architecture/cloud-init

Configuration snippet for 'Start recovery on tty1' service, with a named 'Recovery' step.

```yaml
name: "Start recovery on tty1"  

stages:  

  boot:  

    - name: "Recovery"  

      if: '[ -f "/run/cos/recovery_mode" ]'  

      hostname: "cos-recovery"  

      commands:  

...  


```

--------------------------------

### Manual Bundle Installation with Kairos Agent

Source: https://kairos.io/docs/v4.1.0/advanced/bundles

This command demonstrates how to manually install a bundle using the `kairos-agent` after the initial Kairos installation is complete. Replace the example URL with the desired bundle.

```bash
kairos-agent install-bundle run://quay.io/kairos/community-bundles:cert-manager_latest

```

--------------------------------

### Full Cloud-Config Example with Encrypted Partitions

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

A comprehensive cloud-config example demonstrating automatic installation, persistent partition sizing, creation of an extra partition, and encryption of that partition.

```yaml
install:  
  device: "auto" # Install to the biggest drive  
  auto: true    # Enables auto installation  
  partitions:  
    persistent:  
      size: 500 # Set persistent partition to 500MB (otherwise takes the whole disk)  
  extra-partitions:  
    - name: second_partition  
      size: 100  
      fs: ext2  
      label: PARTITION_TWO  
  encrypted_partitions:  
  - PARTITION_TWO  

```

--------------------------------

### Install Bundle on First Boot

Source: https://kairos.io/docs/v4.1.0/advanced/bundles

Use this configuration to install a bundle right after installation, before booting into the installed system. Replace `<image>` with the actual bundle image URL or path.

```yaml
#cloud-config

bundles:
- targets:
  - run://<image>

```

--------------------------------

### Dynamic Disk Selection with script://

Source: https://kairos.io/docs/v4.1.0/advanced/configuring_partitions

Example cloud-config demonstrating dynamic disk selection for partitioning using a script. The script path is resolved at install time.

```yaml
#cloud-config

stages:
  kairos-install.pre.before:
    - name: "Partition the dynamically selected disk"
      layout:
        device:
          path: "script:///usr/local/bin/pick-disk.sh"
        add_partitions:
          - fsLabel: COS_STATE
            size: 18000
            pLabel: state
          - fsLabel: COS_PERSISTENT
            pLabel: persistent
            size: 0
            filesystem: "ext4"
```

--------------------------------

### Install Kyverno with Cloud-Config

Source: https://kairos.io/docs/v4.1.0/upgrade/kubernetes

Example cloud-config file for installing Kyverno in a Kairos cluster.

```yaml
#cloud-config

hostname: kyverno-{{ trunc 4 .MachineID }}

```

--------------------------------

### Full Cloud-Config for Kairos Installation

Source: https://kairos.io/docs/v4.1.0/examples/core

A comprehensive cloud-config example demonstrating various installation options including device, auto-install, reboot, source image, hostname, user configuration, and K3s enablement.

```yaml
#cloud-config  
  
install:  
 device: "auto"  
 auto: true  
 reboot: true  
 # Here we specify the image that we want to deploy  
 source: "oci:quay.io/kairos/hadron:v0.2.0-standard-amd64-generic-v4.1.0-k3sv1.36.0-k3s1"  
  
hostname: "test"  
users:  
- name: "kairos"  
 passwd: "kairos"  
 ssh_authorized_keys:  
 - github:mudler  
  
k3s:  
 enable: true  

```

--------------------------------

### Aurora Configuration File Example

Source: https://kairos.io/docs/v4.1.0/reference/auroraboot

Example of an aurora.yaml configuration file for AuroraBoot. This file specifies the container image and cloud-config for node setup.

```yaml
container_image: "quay.io/kairos/hadron:v0.2.0-core-amd64-generic-v4.1.0"

cloud_config: |
    #cloud-config

    install:
    auto: true
    device: "auto"
    reboot: true

    # Define the user accounts on the node.
    users:
    - name: kairos                       # The username for the user.
      passwd: kairos                      # The password for the user.
      groups:
      - admin
    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.

```

--------------------------------

### Example Script for Dynamic Disk Selection

Source: https://kairos.io/docs/v4.1.0/advanced/configuring_partitions

A sample shell script that can be used with the 'script://' URI to select a disk for installation.

```sh
#!/bin/sh  

```

--------------------------------

### Cloud-Init Stages Configuration

Source: https://kairos.io/docs/v4.1.0/reference/configuration

Define stages for cloud-init, including network setup and user authorization. This example shows setting up a user 'kairos' with SSH keys from GitHub.

```yaml
stages:
  network:
    - name: "Setup users"
      authorized_keys:
        kairos:
          - github:mudler
```

--------------------------------

### Install Bundle After Installation

Source: https://kairos.io/docs/v4.1.0/advanced/bundles

Use this configuration to install a bundle after the main system installation is complete. This is suitable for bundles designed for post-installation use.

```yaml
#cloud-config
install:
 bundles:
 - targets:
   - run://<image>

```

--------------------------------

### Run Container Image After Installation

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

Boots the 'fedora-qemu' container using the installed disk image after the initial installation is complete. This command is for console-only output and requires the TPM container to remain running.

```bash
# console only
docker run --privileged -v $PWD/tpmstate:/tmp -v $PWD:/work -v /dev/kvm:/dev/kvm --rm -ti fedora-qemu -nographic  
```

--------------------------------

### Example Configuration with Generated Token

Source: https://kairos.io/docs/v4.1.0/reference/kairosctl

An example of a Kairos configuration file using a token generated by `generate-token`.

```yaml
kairos:
  network_token: b3RwOgogIGRodDoKICAgIGludGVydmFsOiA5MjIzMzcyMDM2ODU0Nzc1ODA3CiAgICBrZXk6IFhMMjRYUk1MTlFOQ1pJQTU0SVFLQ1laMk83SENQWEFBU1ZKN0tZSTQ3MzVaUkpKSktRSEEKICAgIGxlbmd0aDogMzIKICBjcnlwdG86CiAgICBpbnRlcnZhbDogOTIyMzM3MjAzNjg1NDc3NTgwNwogICAga2V5OiBMR1dMWFBTUllaU0ZERDdOT0pBNzdKV0ZWQjRHVkZBMjJIWlZPWU1VT0lNSFVYNFZXUURRCiAgICBsZW5ndGg6IDMyCnJvb206IFRtcUt5VnFHQ1ZZam9TRm9CTEVNRGVEdmJzelBkVEdoCnJlbmRlenZvdXM6IGttb3J4Q21sY2NjVVppWmdkSW5xTERvTGJtS3ZGdm9mCm1kbnM6IEZkWVdQc2R4aHdvWHZlb0VzSXNnVHRXbEJUbE9IVHJmCm1heF9tZXNzYWdlX3NpemU6IDIwOTcxNTIwCg==
  offline: false
  reboot: false
  device: ""
  poweroff: false

stages:
  network:
    - name: "Setup users"
      authorized_keys:
        kairos:
          - github:yourhandle!
```

--------------------------------

### Enabling and Starting Keylime Agent Service

Source: https://kairos.io/docs/v4.1.0/examples/keylime

This configuration enables the keylime_agent service to start on boot and then immediately starts the service to begin attestation.

```yaml
- name: "Enable keylime_agent service" # This will request activation but does not ADD the node and starts attestation
  systemctl:
    enable:
      - keylime_agent
    start:
      - keylime_agent
```

--------------------------------

### Use Installed Package

Source: https://kairos.io/docs/v4.1.0/advanced/customizing

Once the system is updated and rebooted, you can use the installed packages.

```bash
kairos@node2:~> figlet kairos rocks!  
```

--------------------------------

### OS Image Examples

Source: https://kairos.io/docs/v4.1.0/reference/artifacts

Illustrative examples of OS image artifact names, demonstrating the naming convention with specific distribution and version details.

```text
kairos-ubuntu-23.04-core-amd64-generic-v4.1.0
```

```text
kairos-ubuntu-23.04-standard-arm64-rpi4-v4.1.0-k3sv1.28.2+k3s1.iso
```

--------------------------------

### Install sysext from local file

Source: https://kairos.io/docs/v4.1.0/examples/trusted-boot-firmware-sysext

Install a sysext raw image from a local file path using the kairos-agent. Useful when the image is already present on the node.

```shell
$ kairos-agent sysext install file:/tmp/firmware-ubuntu-2404.sysext.raw
```

--------------------------------

### Full Cloud-init Stage Example

Source: https://kairos.io/docs/v4.1.0/reference/configuration

A comprehensive example demonstrating various directives within a single 'boot' stage, including systemd services, file manipulation, commands, environment variables, systemctl operations, authorized keys, DNS settings, entity management, and data source providers.

```yaml
#cloud-config

stages:
   # "boot" is the stage
   boot:
     - systemd_firstboot:
         keymap: us
     - files:
        - path: /tmp/bar
          content: |
                    test
          permissions: 0777
          owner: 1000
          group: 100
       if: "[ ! -e /tmp/bar ]"
     - files:
        - path: /tmp/foo
          content: |
                    test
          permissions: 0777
          owner: 1000
          group: 100
       commands:
        - echo "test"
       modules:
       - nvidia
       environment:
         FOO: "bar"
       systctl:
         debug.exception-trace: "0"
       hostname: "foo"
       systemctl:
         enable:
         - foo
         disable:
         - bar
         start:
         - baz
         mask:
         - foobar
       authorized_keys:
          user:
          - "github:mudler"
          - "ssh-rsa ...."
       dns:
         path: /etc/resolv.conf
         nameservers:
         - 8.8.8.8
       ensure_entities:
       -  path: /etc/passwd
          entity: |
                  kind: "user"
                  username: "foo"
                  password: "pass"
                  uid: 0
                  gid: 0
                  info: "Foo!"
                  homedir: "/home/foo"
                  shell: "/bin/bash"
       delete_entities:
       -  path: /etc/passwd
          entity: |
                  kind: "user"
                  username: "foo"
                  password: "pass"
                  uid: 0
                  gid: 0
                  info: "Foo!"
                  homedir: "/home/foo"
                  shell: "/bin/bash"
       datasource:
        path: "/usr/local/etc"
        providers:
          - "digitalocean"
          - "aws"
          - "gcp"

```

--------------------------------

### Multiple Cloud-init Stages Example

Source: https://kairos.io/docs/v4.1.0/reference/configuration

Demonstrates defining commands for different stages ('boot' and 'initramfs') to execute at specific points in the node's lifecycle. Includes conditional execution based on file existence.

```yaml
#cloud-config

stages:
   boot:
   - commands:
     - echo "hello from the boot stage"
   initramfs:
   - commands:
     - echo "hello from the boot stage"
   - commands:
     - echo "so much wow, /foo/bar bar exists!"
     if: "[ -e /foo/bar ]"

```

--------------------------------

### Prepare GRUB Configuration for ISO Override

Source: https://kairos.io/docs/v4.1.0/reference/auroraboot

This example shows how to create a directory structure and download a custom GRUB configuration file to override the default ISO boot menu.

```bash
mkdir -p data/boot/grub2
# You can replace this step with your own grub config. This GRUB configuration is the boot menu of the ISO
wget https://raw.githubusercontent.com/kairos-io/packages/main/packages/livecd/grub2/config/grub_live_bios.cfg -O data/boot/grub2/grub.cfg  

```

--------------------------------

### Cloud-Config with Auto Install Block

Source: https://kairos.io/docs/v4.1.0/examples/p2p_e2e

Extends the basic cloud-config by adding an 'install' block to enable automatic installation and reboot. This ensures the node is ready for cluster participation after initial setup.

```yaml
install:
 auto: true
 device: "auto"
 reboot: true

```

--------------------------------

### Kairos-Init Steps and Stages Information

Source: https://kairos.io/docs/v4.1.0/reference/kairos-factory

This is an example output from the `kairos-init steps-info` command, listing various stages and steps available during the image build process, along with their descriptions. This information is subject to change.

```log
2025-07-07T09:53:05Z INF [7] Starting kairos-init version 59628ad  
2025-07-07T09:53:05Z INF [7] Step name & Description  
2025-07-07T09:53:05Z INF [7] --------------------------------------------------------  
2025-07-07T09:53:05Z INF [7] "branding": applies the branding for the system  
2025-07-07T09:53:05Z INF [7] "cleanup": cleans up the system of unneeded packages and files  
2025-07-07T09:53:05Z INF [7] "cloudconfigs": installs the cloud-configs for the system  
2025-07-07T09:53:05Z INF [7] "grub": configures the grub bootloader  
2025-07-07T09:53:05Z INF [7] "init": The full init stage, which includes kairosRelease, kubernetes, initrd, services, workarounds and cleanup steps  
2025-07-07T09:53:05Z INF [7] "initramfsConfigs": configures the initramfs for the system  
2025-07-07T09:53:05Z INF [7] "initrd": generates the initrd  
2025-07-07T09:53:05Z INF [7] "install": The full install stage, which includes installPackages, kubernetes, cloudconfigs, branding, grub, services, kairosBinaries, providerBinaries, initramfsConfigs and miscellaneous steps  
2025-07-07T09:53:05Z INF [7] "installKernel": installs the kernel packages  
2025-07-07T09:53:05Z INF [7] "installPackages": installs the base system packages  
2025-07-07T09:53:05Z INF [7] "kairosBinaries": installs the kairos binaries  
2025-07-07T09:53:05Z INF [7] "kairosRelease": creates and fills the /etc/kairos-release file  
2025-07-07T09:53:05Z INF [7] "kernel": installs the kernel  
2025-07-07T09:53:05Z INF [7] "kubernetes": installs the kubernetes provider  
2025-07-07T09:53:05Z INF [7] "miscellaneous": applies miscellaneous configurations  
2025-07-07T09:53:05Z INF [7] "providerBinaries": installs the kairos provider binaries for k8s  
2025-07-07T09:53:05Z INF [7] "services": creates and enables required services  
2025-07-07T09:53:05Z INF [7] "workarounds": applies workarounds for known issues  
```

--------------------------------

### Create Build Directory and Navigate

Source: https://kairos.io/docs/v4.1.0/installation/automated

Commands to create a new directory for building the ISO and then navigate into it.

```bash
$ mkdir -p build
$ cd build

```

--------------------------------

### Example Workflow for Managing System Extensions

Source: https://kairos.io/docs/v4.1.0/advanced/sys-extensions

Demonstrates a typical workflow: downloading an extension, enabling it for the active profile with immediate activation, listing enabled extensions, and finally removing it completely.

```bash
# Download a disk image over HTTPS  

kairos-agent sysext install https://example.org/extensions/k3sv1.32.1.raw  

# Enable for the active profile and activate it live  

kairos-agent sysext enable --active --now k3s  

# See what’s currently enabled for active  

kairos-agent sysext list --active  

# Fully remove it and clean up live state  

kairos-agent sysext remove --now k3s  

```

--------------------------------

### Make a Directory Persistent After Installation

Source: https://kairos.io/docs/v4.1.0/advanced/customizing

Use a cloud-config file in the `/oem` folder to define custom bind mounts that will be persistent after the system is installed. This example makes `/var/lib/docker` persistent.

```yaml
#cloud-config

stages:
  rootfs:
  - name: "user_custom_mount"
    environment_file: "/run/cos/custom-layout.env"
    environment:
       CUSTOM_BIND_MOUNTS: "/var/lib/docker"
```

--------------------------------

### Prepare files for ISO build

Source: https://kairos.io/docs/v4.1.0/installation/automated

Sets up the necessary directory structure and downloads a default GRUB configuration for the ISO. This step can be customized with your own GRUB configuration.

```bash
$ IMAGE=<scheme://host[:port]/path[:tag]>
$ mkdir -p files-iso/boot/grub2
$ wget https://raw.githubusercontent.com/kairos-io/packages/main/packages/livecd/grub2/config/grub_live_bios.cfg -O files-iso/boot/grub2/grub.cfg
```

--------------------------------

### Install and Run goverify for EFI Signature Verification

Source: https://kairos.io/docs/v4.1.0/reference/troubleshooting

Install the goverify tool using go get and then run it to verify EFI executable signatures. This ensures the integrity of boot components.

```bash
go get -u github.com/Foxboron/go-uefi/cmd/goverify
```

```bash
goverify
```

--------------------------------

### Download Example Partition Configuration

Source: https://kairos.io/docs/v4.1.0/installation/nvidia_agx_orin

Use this command to download the example partition configuration file for the AGX Orin board. This file serves as a baseline for modifying partition layouts.

```bash
wget 'https://kairos.io/examples/board-configs/flash_t234_qspi_sdmmc.xml' -O ./bootloader/generic/cfg/flash_t234_qspi_sdmmc.xml
```

--------------------------------

### Set up DNS at Boot Stage

Source: https://kairos.io/docs/v4.1.0/reference/configuration

Configure DNS settings for the /etc/resolv.conf file during the boot stage using extended syntax.

```yaml
#cloud-config

stages:
  boot:
    - name: "DNS settings"
      dns:
        path: /etc/resolv.conf
        nameservers:
          - 8.8.8.8

```

--------------------------------

### Get Kairos Agent Boot State

Source: https://kairos.io/docs/v4.1.0/installation/aws

Check the current boot state of the Kairos agent to confirm if the installation process has completed and the system is in 'active' mode. Expect 'active_boot' for a successful installation.

```bash
kairos-agent state get boot
```

--------------------------------

### Cloud Config Example for Offline Encryption Scenario

Source: https://kairos.io/docs/v4.1.0/advanced/partition_encryption

A full cloud-config example for offline encryption, specifying the 'COS_PERSISTENT' partition. It also includes basic system configuration like hostname and user setup.

```yaml
#cloud-config

install:
  encrypted_partitions:
  - COS_PERSISTENT

hostname: metal-{{ trunc 4 .MachineID }}
users:
- name: kairos
  # Change to your pass here
  passwd: kairos
  groups:
  - admin
  ssh_authorized_keys:
  # Replace with your github user and un-comment the line below:
  # - github:mudler

```

--------------------------------

### Prepare SDK Rootfs and Bootloader

Source: https://kairos.io/docs/v4.1.0/installation/nvidia_orin_nx

Navigate into the SDK directory, disable extlinux, unpack the Kairos Ubuntu image into the rootfs, and create a dummy extlinux configuration.

```bash
cd Linux_for_Tegra

# Drop extlinux  

echo "" > ./bootloader/extlinux.conf  

# This is needed so the SDK doesn't complain of missing files (not really used in the flash process)  

IMAGE=quay.io/kairos/ubuntu:22.04-core-arm64-nvidia-jetson-orin-nx-v4.1.0  

docker run -ti --rm -v $PWD/rootfs:/rootfs quay.io/luet/base util unpack "$IMAGE" /rootfs  

# workaround needed (SDK writes to the symlink)  

rm rootfs/boot/initrd  

# Extlinux is required by the SDK - so we fake it in our root (it will not be there eventually)  

mkdir -p rootfs/boot/extlinux/  

echo "" > rootfs/boot/extlinux/extlinux.conf  
```

--------------------------------

### Download Baseline Partition Configuration

Source: https://kairos.io/docs/v4.1.0/installation/nvidia_orin_nx

Use this command to download the example partition configuration file for the Orin NX board. This serves as a baseline for modifications.

```bash
wget 'https://kairos.io/examples/board-configs/flash_t234_qspi_nvme.xml' -O ./bootloader/generic/cfg/flash_t234_qspi_nvme.xml
```

--------------------------------

### Get Kairos-Init Steps Info

Source: https://kairos.io/docs/v4.1.0/reference/kairos-factory

This Dockerfile snippet demonstrates how to run the `steps-info` command from kairos-init to list available stages and steps. It uses a multi-stage build to copy the kairos-init binary and then execute the command.

```dockerfile
FROM quay.io/kairos/kairos-init:v0.13.0 AS kairos-init  

FROM ubuntu:24.04  
RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init /kairos-init steps-info  
```

--------------------------------

### Full Cloud-Config with KubeVIP and HA

Source: https://kairos.io/docs/v4.1.0/installation/p2p

A complete cloud-config example demonstrating KubeVIP with High Availability (HA) and P2P networking setup.

```yaml
#cloud-config

install:
  auto: true
  device: "auto"
  reboot: true
  
hostname: "kubevip-{{ trunc 4 .MachineID }}"
users:
- name: "kairos"
  passwd: "kairos"
  ssh_authorized_keys:
  - github:mudler
  
p2p:
 network_token: "..."
 ha:
  master_nodes: 2
 vpn:
  # Disable VPN, so traffic is not configured with a VPN
  create: false
  use: false
 
kubevip:
  eip: "192.168.1.110"
```

--------------------------------

### Basic Cloud-Config Example

Source: https://kairos.io/docs/v4.1.0/advanced/creating_custom_cloud_images

Defines a hostname and user, and specifies a custom OCI image for system reset during the first boot.

```yaml
#cloud-config

hostname: kairos-{{ trunc 4 .MachineID }}

users:
- name: "kairos"
  passwd: kairos
  groups:
  - admin

reset:
  system:
    source: "oci:quay.io/kairos/opensuse:leap-15.6-standard-amd64-generic-master-k3sv1.32.1-rc2-k3s1"

```

--------------------------------

### Modifying GRUB Options Post-Installation

Source: https://kairos.io/docs/v4.1.0/reference/configuration

Provides an example of how to change GRUB options, such as 'rd.neednet=1', after installation by directly editing the /oem/grubenv file using grub2-editenv.

```bash
grub2-editenv /oem/grubenv set extra_cmdline="rd.neednet=1"
```

--------------------------------

### Run Container Image with ISO for Installation

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

Launches the 'fedora-qemu' container to boot an ISO file for installation. This command mounts necessary volumes and devices for QEMU to operate correctly. It is intended for console-only output.

```bash
# console only
docker run --privileged -v $PWD/tpmstate:/tmp -v $PWD:/work -v /dev/kvm:/dev/kvm --rm -ti fedora-qemu -nographic -cdrom kairos-hadron-v0.2.0-core-amd64-generic-v4.1.0.uki.iso  
```

--------------------------------

### Specify Image Source in Cloud-Config

Source: https://kairos.io/docs/v4.1.0/examples/core

Configure the `install.source` field in your cloud-config file to specify the container image you want to deploy. This is a minimal configuration to get started.

```yaml
#cloud-config  
install:  
 # Here we specify the image that we want to deploy  
 source: "oci:quay.io/kairos/hadron:v0.2.0-standard-amd64-generic-v4.1.0-k3sv1.36.0-k3s1"  

```

--------------------------------

### Kairos Cloud-Config for MetalLB Installation

Source: https://kairos.io/docs/v4.1.0/examples/bundles

This cloud-config file is used during Kairos setup to automatically configure MetalLB. It specifies the MetalLB version and the IP address pool for services.

```yaml
#cloud-config  
  
hostname: metal-{{ trunc 4 .MachineID }}  
users:  
- name: kairos  
  # Change to your pass here  
  passwd: kairos  
  groups:  
  - admin  
  ssh_authorized_keys:  
  # Replace with your github user and un-comment the line below:  
  # - github:mudler  
  
k3s:
  enabled: true  
  args:  
  - --disable=traefik,servicelb  
  
# Specify the bundle to use  
bundles:
- targets:  
  - run://quay.io/kairos/community-bundles:metallb_latest  
  
# Specify metallb settings, available only with the bundle.  
metallb:
  version: 0.13.7  
  address_pool: 192.168.1.10-192.168.1.20  

```

--------------------------------

### Build Keylime Agent Dockerfile

Source: https://kairos.io/docs/v4.1.0/examples/keylime

Dockerfile to build the Keylime agent for a Kairos derivative. This example uses Ubuntu 24.04 and installs necessary build dependencies, clones the rust-keylime repository, and builds/installs the agent.

```dockerfile
# Build the keylime agent  

FROM ubuntu:24.04 AS keylime-build  

RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git gcc libclang-dev libssl-dev libtss2-dev libzmq3-dev pkg-config rustup make && rm -rf /var/lib/apt/lists/*  

WORKDIR /keylime  

RUN git clone --depth 1 --branch v0.2.7 https://github.com/keylime/rust-keylime.git /keylime  

# Set up install destination dir so we can reuse the build artifacts for our Kairos image  

ENV DESTDIR=/keylime-output  

RUN rustup default stable && make && make install  
  
```

--------------------------------

### Complete Cloud Configuration for Debugging Station

Source: https://kairos.io/docs/v4.1.0/development/debugging-station

A comprehensive cloud-config file to set up a Kairos node, install k3s, enable entangle, and expose SSH. This example includes user configuration and bundle targeting.

```yaml
#cloud-config  
  
install:  
 device: "auto"  
 auto: true  
 reboot: true  
  
hostname: debugging-station-{{ trunc 4 .MachineID }}  
  
users:  
- name: kairos  
  passwd: kairos  
  groups:  
  - admin  
  ssh_authorized_keys:  
  - github:mudler  
  
k3s:  
  enabled: true  
  
# Specify the bundle to use  
bundles:  
- targets:  
  - run://quay.io/kairos/community-bundles:cert-manager_latest  
  - run://quay.io/kairos/community-bundles:kairos_latest  
  
kairos:  
  entangle:  
    enable: true  
  
write_files:  
- path: /var/lib/rancher/k3s/server/manifests/expose-ssh.yaml  
  permissions: "0644"  
  owner: "root"  
  content: |  
      apiVersion: v1  
      kind: Secret  
      metadata:  
        name: ssh-entanglement  
        namespace: kube-system  
      type: Opaque  
      stringData:  
        network_token: ___GENERATED TOKEN HERE___  
      ---
      apiVersion: entangle.kairos.io/v1alpha1  
      kind: Entanglement  
      metadata:  
        name: ssh-entanglement  
        namespace: kube-system  
      spec:  
         serviceUUID: "ssh"  
         secretRef: "ssh-entanglement"  
         host: "127.0.0.1"  
         port: "22"  
         hostNetwork: true  

```

--------------------------------

### Add Files to ISO Filesystem using build-iso

Source: https://kairos.io/docs/v4.1.0/reference/auroraboot

Prepare extra files and include them in the ISO filesystem root using the `--overlay-iso` flag with `build-iso`.

```bash
# Prepare extra files to include in the ISO

mkdir -p files-iso/extra

cp my-installer-script.sh files-iso/extra/


docker run -v "$PWD"/files-iso:/files-iso \
             -v "$PWD"/build:/tmp/auroraboot \
             --rm -ti quay.io/kairos/auroraboot \
             build-iso --overlay-iso /files-iso \
             --output /tmp/auroraboot $IMAGE

```

--------------------------------

### Keylime Agent Quote Request Log Example

Source: https://kairos.io/docs/v4.1.0/examples/keylime

Shows an agent log entry indicating a GET request for an integrity quote with specific parameters like nonce, mask, and IMA measurement entry.

```log
Jul 10 12:55:39 localhost keylime_agent[1551]:  INFO  keylime_agent                        > GET invoked from "192.168.122.31" with uri /v2.1/quotes/integrity?nonce=TMywGq9gEgYy8QaptsB1&mask=0x400&partial=1&ima_ml_entry=1739  

Jul 10 12:55:39 localhost keylime_agent[1551]:  INFO  keylime_agent::quotes_handler        > GET integrity quote returning 200 response  

Jul 10 12:55:41 localhost keylime_agent[1551]:  INFO  keylime_agent                        > GET invoked from "192.168.122.31" with uri /v2.1/quotes/integrity?nonce=eyI1bo2HpS081kM1FbnQ&mask=0x400&partial=1&ima_ml_entry=1739  

Jul 10 12:55:42 localhost keylime_agent[1551]:  INFO  keylime_agent::quotes_handler        > GET integrity quote returning 200 response  

Jul 10 12:55:44 localhost keylime_agent[1551]:  INFO  keylime_agent                        > GET invoked from "192.168.122.31" with uri /v2.1/quotes/integrity?nonce=3TStNCteiVm5NC0dCraW&mask=0x400&partial=1&ima_ml_entry=1739  

Jul 10 12:55:44 localhost keylime_agent[1551]:  INFO  keylime_agent::quotes_handler        > GET integrity quote returning 200 response  
```

--------------------------------

### Configure Disk Partitions in Boot Stage

Source: https://kairos.io/docs/v4.1.0/reference/stage_modules

Use this snippet to set up disk partitions, including expanding the last partition and adding new ones with specific labels and sizes, during the boot stage. Ensure all sizes are in MiB.

```yaml
#cloud-config

stages:
  boot:
    - name: "Repart disk"
      layout:
        device:
          # It will partition a device including the given filesystem label
          # or partition label (filesystem label matches first) or the device
          # provided in 'path'. The label check has precedence over path when
          # both are provided.
          # 'path' also accepts a "script:///path/to/script.sh [args...]"
          # value: everything after the "script://" prefix is treated as the
          # command, which is executed and whose stdout is used as the device
          # path at runtime. If the command includes spaces or arguments,
          # quote the entire YAML value.
          label: "COS_RECOVERY"
          path: "/dev/sda"
        # Only last partition can be expanded and it happens after all the other
        # partitions are created. size: 0 means all available free space
        expand_partition:
          size: 4096
        add_partitions:
          - fsLabel: "COS_STATE"
            size: 8192
            # No partition label is applied if omitted
            pLabel: "state"
          - fsLabel: "COS_PERSISTENT"
            # default filesystem is ext2 if omitted
            filesystem: "ext4"
```

--------------------------------

### Start Pixiecore with AuroraBoot

Source: https://kairos.io/docs/v4.1.0/installation/netboot

Launches Pixiecore using AuroraBoot to serve Kairos netboot artifacts. Pixiecore acts as a ProxyDHCP server, integrating with existing DHCP setups to provide the kernel and initrd to PXE-booting machines.

```docker
docker run --rm --net host -v $PWD:/work quay.io/kairos/auroraboot \
    start-pixie /work/cloud-config.yaml /work/out/kairos.squashfs 0.0.0.0 8090 \
                /work/out/kairos-initrd /work/out/kairos-kernel
```

--------------------------------

### Example Active Configuration File

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

Shows the content of an active.conf file, specifying the EFI boot file and the title displayed in the boot menu.

```shell
efi /EFI/kairos/active.efi
title Kairos
```

--------------------------------

### Build ISO from Directory with Trusted Boot Keys

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

Creates an installable ISO medium from a directory containing the OS root filesystem, integrating Secure Boot and TPM keys.

```bash
# Assuming you have a "rootfs" directory with the content of the OS  

# If the image is in a directory ($PWD/rootfs) you can use the following command  

docker run -ti --rm -v $PWD/build:/result -v $PWD/rootfs:/rootfs -v $PWD/keys/:/keys quay.io/kairos/auroraboot:v0.20.1 build-uki -t iso -d /result/ --public-keys /keys --tpm-pcr-private-key $PATH_TO_TPM_KEY --sb-key $PATH_TO_SB_KEY --sb-cert $PATH_TO_SB_CERT dir:/rootfs/
```

--------------------------------

### Dockerfile using Kairos Factory for Kubeadm Provider Image

Source: https://kairos.io/docs/v4.1.0/examples/kubeadm-provider

This Dockerfile utilizes the Kairos Factory method to build an image with Kubernetes components and the provider-kubeadm. It starts from a Kairos base, installs Kubernetes packages, and downloads the provider binary.

```dockerfile
FROM quay.io/kairos/kairos-init:v0.13.0 AS kairos-init  


FROM ubuntu:24.04  
ARG VERSION=1.0.0  
RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init /kairos-init --version "${VERSION}"  
RUN curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg  
RUN echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | tee /etc/apt/sources.list.d/kubernetes.list  


# Install required packages  
RUN apt-get update && apt-get install -y --no-install-recommends \ 
    socat \ 
    conntrack \ 
    containerd \ 
    runc \ 
    kubelet \ 
    kubeadm \ 
    kubectl \ 
 && apt-get clean && rm -rf /var/lib/apt/lists/*   
RUN mkdir -p /system/providers && curl -L https://github.com/kairos-io/provider-kubeadm/releases/download/v4.7.0-rc.4/agent-provider-kubeadm-v4.7.0-rc.4-linux-amd64.tar.gz | tar -xz -C /system/providers/  

```

--------------------------------

### Custom Partitioning in Pre-Install Stage

Source: https://kairos.io/docs/v4.1.0/reference/stage_modules

This example demonstrates creating custom disk partitions using `parted` within the `kairos-install.pre.before` stage. It ensures existing partitions are not formatted and defines multiple new partitions with specific labels, sizes, and file systems. Warning: You are responsible for ensuring partition sizes fit within the disk.

```yaml
#cloud-config

install:
  # Make sure the installer won't delete our custom partitions
  no-format: true
  
stages:
  kairos-install.pre.before:
  - if:  '[ -e /dev/vda ]'
    name: "Create partitions"
    commands:
      - | 
        parted --script --machine -- /dev/vda mklabel msdos 
    layout:
      device:
        path: /dev/vda
      expand_partition:
        size: 0 # All available space
      add_partitions:
        # all sizes bellow are in MB
        - fsLabel: COS_OEM
          size: 64
          pLabel: oem
        - fsLabel: COS_RECOVERY
          size: 8500
          pLabel: recovery
        - fsLabel: COS_STATE
          size: 18000
          pLabel: state
        - fsLabel: COS_PERSISTENT
          pLabel: persistent
          size: 25000
          filesystem: "ext4"
```

--------------------------------

### Add Files to OS Rootfs using build-iso

Source: https://kairos.io/docs/v4.1.0/reference/auroraboot

Prepare a rootfs overlay with custom binaries and add them to the OS rootfs using the `--overlay-rootfs` flag with `build-iso`.

```bash
# Prepare a rootfs overlay with a custom binary

mkdir -p rootfs-overlay/usr/local/bin
cp my-custom-tool rootfs-overlay/usr/local/bin/


docker run -v "$PWD"/rootfs-overlay:/rootfs-overlay \
             -v "$PWD"/build:/tmp/auroraboot \
             --rm -ti quay.io/kairos/auroraboot \
             build-iso --overlay-rootfs /rootfs-overlay \
             --output /tmp/auroraboot $IMAGE

```

--------------------------------

### Automated Install Configuration Block

Source: https://kairos.io/docs/v4.1.0/installation/automated

This block specifies parameters for automated Kairos installations, including the target device, reboot and poweroff settings, and a list of bundles to install.

```yaml
install:
  # Device for automated installs
  device: "/dev/sda"
  # Reboot after installation
  reboot: true
  # Power off after installation
  poweroff: true
  # Set to true to enable automated installations
  auto: true
  # A list of bundles
  bundles:
    -  quay.io/kairos/packages:k9s-utils-0.26.7

```

--------------------------------

### Bash Script to Build Raw Images with QEMU

Source: https://kairos.io/docs/v4.1.0/reference/build_raw_images_with_qemu

This script automates the creation of raw bootable images for Kairos using QEMU. It takes a cloud-init YAML file and an optional Kairos ISO as arguments. The script sets up a build environment, creates a cloud-init ISO, generates a raw disk image, and then boots QEMU with these components.

```bash
#!/bin/bash  
# Generates raw bootable images with qemu  
set -ex  
CLOUD_INIT=${1:-cloud_init.yaml}  
QEMU=${QEMU:-qemu-system-x86_64}  
ISO=${2:-iso.iso}  

mkdir -p build  
pushd build  
touch meta-data  
cp -rfv $CLOUD_INIT user-data  

mkisofs -output ci.iso -volid cidata -joliet -rock user-data meta-data  
truncate -s "+$((20000*1024*1024))" disk.raw  

${QEMU} -m 8096 -smp cores=2 \  
        -nographic -cpu host \  
        -serial mon:stdio \  
        -rtc base=utc,clock=rt \  
        -chardev socket,path=qga.sock,server,nowait,id=qga0 \  
        -device virtio-serial \  
        -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \  
        -drive if=virtio,media=disk,file=disk.raw \  
        -drive format=raw,media=cdrom,readonly=on,file=$ISO \  
        -drive format=raw,media=cdrom,readonly=on,file=ci.iso \  
        -boot d \  
        -enable-kvm  

```

--------------------------------

### Install Cert-Manager

Source: https://kairos.io/docs/v4.1.0/advanced/partition_encryption

Installs the cert-manager on Kubernetes, a prerequisite for deploying the KMS.

```bash
kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
kubectl wait --for=condition=Available deployment --timeout=2m -n cert-manager --all
```

--------------------------------

### AuroraBoot Configuration File Example

Source: https://kairos.io/docs/v4.1.0/reference/auroraboot

Example configuration file for AuroraBoot, detailing parameters like artifact versions, release versions, flavor, repository, and network settings.

```yaml
# Corresponding artifact versions from the kairos release page (e.g. kubernetes version included)  
artifact_version: "v..."  
# Version of the release in github  
release_version: "v4.1.0"  
  
# Flavor  lavor: "hadron"  
  
# Github repository  
repository: "kairos-io/kairos"  
  
# Container image (takes over)  
container_image: "..."  
  
# Disable netboot  
disable_netboot: true  
  
# Disable http server for serving offline generated ISOs  
disable_http_server: true  
  
# Specify a directory that will be used by auroraboot to download artifacts  
# Reuse the same to cache artifacts.  
state_dir: "/tmp/auroraboot"  
  
# Default http binding port for offline ISO generation  
listen_addr: ":8080"  
  
```

--------------------------------

### Auroraboot Example: Building a Configuration Extension

Source: https://kairos.io/docs/v4.1.0/advanced/sys-extensions

Example of successfully building a configuration extension named 'grype sysext' from a Docker image using Auroraboot. The output is a raw image file.

```bash
$ docker run -v "$PWD":/build/ -v /tmp/keys/:/keys -v /var/run/docker.sock:/var/run/docker.sock --rm -ti quay.io/kairos/auroraboot:v0.20.1 confext --private-key=/keys/db.key --certificate=/keys/db.pem --output /build grype sysext
2024-09-16T14:59:36Z INF Starting auroraboot version  
2024-09-16T14:59:36Z INF 🚀 Start confext creation  
2024-09-16T14:59:36Z INF 💿 Getting image info  
2024-09-16T14:59:36Z INF 📤 Extracting archives from image layer  
2024-09-16T14:59:37Z INF 📦 Packing confext into raw image  
2024-09-16T14:59:37Z INF 🎉 Done confext creation output=/build/grype.confext.raw  

```

--------------------------------

### Install cert-manager

Source: https://kairos.io/docs/v4.1.0/reference/entangle

Installs cert-manager, a prerequisite for Entangle. Ensure the deployment is available before proceeding.

```bash
kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml  

kubectl wait --for=condition=Available deployment --timeout=2m -n cert-manager --all  
```

--------------------------------

### Configuration File with Version and Cmdline

Source: https://kairos.io/docs/v4.1.0/installation/trustedboot

An example configuration file including OS version and command line arguments, generated using specific auroraboot flags.

```shell
cmdline awesome=true
title Awesome OS
efi /EFI/kairos/active.efi
version v4.1.0
```

--------------------------------

### Example Binary Names

Source: https://kairos.io/docs/v4.1.0/reference/artifacts

Examples of Kairos binaries named according to the specified convention.

```text
kairosctl-v2.3.0-Linux-386.tar.gz
```

```text
provider-kairos-2.3.0-Windows-amd64.tar.gz
```

```text
kairos-agent-v2.1.10-Linux-arm64.tar.gz
```
Tokens:
Raw