Kairos Documentation

Kairos is an immutable, container-based Linux meta-distribution designed for edge Kubernetes. It allows developers to build bootable Kubernetes and OS images using a workflow as simple as writing a Dockerfile.

Key capabilities include:

• Immutable Infrastructure: Prevents infrastructure drift by using immutable OS images.
• Container-based Builds: Build OS and Kubernetes images using container principles.
• Lifecycle Management: Manage provisioning, building, and upgrading clusters via Kubernetes-native patterns.
• Atomic Upgrades: Perform secure, risk-free A/B atomic upgrades by pushing new images to a container registry.
• Optional P2P Mesh: Automates node bootstrapping and coordination using a distributed ledger.
• Distribution Agnostic: Can be used to spin up Kubernetes clusters with various Linux distributions.

Once you have built a custom container image (e.g., ubuntu-non-hwe:22.04), you can use it as the BASE_IMAGE in your build configuration to generate final Kairos ISOs or raw images.

For detailed instructions on the actual image generation process, refer to the osbuilder-tools or AuroraBoot documentation within the Kairos project.

To build the Fedora FIPS image and run it using QEMU, use the provided shell scripts in the example directory:

1. Build the ISO: bash build.sh
2. Start the ISO with QEMU: bash run.sh

To build and run the Kairos Ubuntu focal FIPS image using the provided example scripts, follow these steps:

1. Edit pro-attach-config.yaml with your token.
2. Run the build script: bash build.sh.
3. Start the ISO using QEMU: bash run.sh.

Important Notes:

• The system does not enable FIPS in kernel space by default.
• The LiveCD does not run in FIPS mode.
• Ubuntu FIPS support is limited to 16.04 LTS, 18.04 LTS, or 20.04 LTS.

# Edit pro-attach-config.yaml first
bash build.sh
bash run.sh

To build the Rocky Linux FIPS image and run it using QEMU, use the provided shell scripts in the example directory:

1. Build the ISO: bash build.sh
2. Start the ISO with QEMU: bash run.sh

To build and run a Kairos Ubuntu jammy (22.04) FIPS image using the provided example, follow these steps:

1. Edit pro-attach-config.yaml with your Ubuntu Pro token.
2. Execute the build script: bash build.sh.
3. Start the resulting ISO using QEMU via the provided script: bash run.sh.

Note: The system does not enable FIPS in kernel space by default. To ensure FIPS is enabled during installation, you must provide a cloud-config file that includes fips=1 in the GRUB options.

# Edit pro-attach-config.yaml first
bash build.sh
bash run.sh

By default, Kairos-based Ubuntu images use HWE (Hardware Enablement) kernels. If your use case requires a specific non-HWE kernel, you must build a custom base image and then use it as your BASE_IMAGE when generating ISOs or raw images.

To build a non-HWE base image using the provided example, navigate to the example directory and use docker build to create an image tagged with your desired version.

$ cd examples/builds/ubuntu-non-hwe
$ docker build -t ubuntu-non-hwe:22.04 .

FIPS is not enabled by default in kernel space. To install a system with FIPS enabled, you must provide a cloud-config file that includes fips=1 in the grub_options.extra_cmdline field.

Important Requirements:

• You must add selinux=0 to the command line because SELinux is not yet supported and must be explicitly disabled.
• Note that the LiveCD itself does not run in FIPS mode; FIPS mode is enabled in the installed system via these boot options.

#cloud-config

install:
  # ...
  # Set grub options
  grub_options:
    # additional Kernel option cmdline to apply
    extra_cmdline: "fips=1 selinux=0"

FIPS is not enabled by default in kernel space. To install a system with FIPS enabled, you must provide a cloud-config file that adds fips=1 to the grub_options.extra_cmdline.

Important Requirements:

• You must add selinux=0 to the extra_cmdline because SELinux is not yet supported and must be explicitly disabled.
• Note that the LiveCD itself does not run in FIPS mode; FIPS mode is applied to the installed system.

#cloud-config

install:
  # ...
  # Set grub options
  grub_options:
    # additional Kernel option cmdline to apply
    extra_cmdline: "fips=1 selinux=0"

To install Kairos with FIPS enabled, you must include fips=1 in the extra_cmdline within the grub_options section of your #cloud-config file.

Important Notes:

• The modules.fips file is required because Ubuntu's version of dracut may lack two necessary modules in the initramfs.
• The LiveCD does not run in FIPS mode by default. To enable FIPS mode while running the LiveCD, append fips=1 to the kernel command line in the boot menu.

#cloud-config

install:
  # ...
  # Set grub options
  grub_options:
    # additional Kernel option cmdline to apply
    extra_cmdline: "fips=1"