Cloud init based

Kairos supports the standard cloud-init syntax and its own extended syntax to allow to configure a system declaratively with a cloud-config centric approach.

If you are not familiar with the concepts of cloud-init, official cloud-init is a recommended read.

Configuration persistency

Kairos is an Immutable OS and the only configuration that is persistent across reboots is the cloud-init configuration. Multiple cloud-init files can be present in the system and Kairos will read them and process them in sequence (lexicographic order) allowing to extend the configuration with additional pieces also after deployment, or to manage logical configuration pieces separately.

In Kairos the /oem directory keeps track of all the configuration of the system and stores the configuration files. Multiple files are allowed and they are all executed during the various system stages. /usr/local/cloud-config can be optionally used as well to store cloud config files in the persistent partition instead. /system/oem is instead reserved to default cloud-init files that are shipped by the base OS image.

By using the standard cloud-config syntax, a subset of the functionalities are available and the settings will be executed in the boot stage.

Boot stages

During boot the stages are emitted in an event-based pattern until a system completes its boot process


The events can be used in the cloud-config extended syntax to hook into the various stages, which can allow to hook inside the different stages of a node lifecycle.

For instance, to execute something before reset is sufficient to add the following to the config file used to bootstrap a node:

name: "Run something before reset"
     - name: "Setting"
       - | 
          echo "Run a command before reset the node!"

Below there is a detailed list of the stages available that can be used in the cloud-init configuration files:

rootfsThis is the earliest stage, running before switching root, just right after the root is mounted in /sysroot and before applying the immutable rootfs configuration. This stage is executed over initrd root, no chroot is applied.
initramfsThis is still an early stage, running before switching root. Here you can apply radical changes to the booting setup of Elemental. Despite this is executed before switching root this exection runs chrooted into the target root after the immutable rootfs is set up and ready.
bootThis stage is executed after initramfs has switched root, during the systemd bootup process.
fsThis stage is executed when fs is mounted and is guaranteed to have access to the state and persistent partitions ( COS_STATE and COS_PERSISTENT respectively).
networkThis stage is executed when network is available
reconcileThis stage is executed 5m after boot and periodically each 60m.
after-installThis stage is executed after installation of the OS has ended
after-install-chrootThis stage is executed after installation of the OS has ended.
after-upgradeThis stage is executed after upgrade of the OS has ended.
after-upgrade-chrootThis stage is executed after upgrade of the OS has ended (chroot call).
after-resetThis stage is executed after reset of the OS has ended.
after-reset-chrootThis stage is executed after reset of the OS has ended (chroot call).
before-installThis stage is executed before installation
before-upgradeThis stage is executed before upgrade
before-resetThis stage is executed before reset

Note: Steps executed at the chroot stage are running inside the new OS as chroot, allowing to write persisting changes to the image, for example by downloading and installing additional software.

In case you’re using a standard image, with the Kairos provider, then these other stages are also available

provider-kairos.bootstrap.before.The provider fires this stage before starting to bootstrap K3S.
provider-kairos.bootstrap.after.The provider fires this stage after it finished bootstrapping K3S.


When a Kairos boots it creates sentinel files in order to allow to execute cloud-init steps programmaticaly.

  • /run/cos/recovery_mode is being created when booting from the recovery partition
  • /run/cos/live_mode is created when booting from the LiveCD

To execute a block using the sentinel files you can specify: if: '[ -f "/run/cos/..." ]', for instance: