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

Kairos-boot-events

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"
stages:
   before-reset:
     - name: "Setting"
       commands:
       - | 
          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:

Stage Description
rootfs This 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.
initramfs This 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.
boot This stage is executed after initramfs has switched root, during the systemd bootup process.
fs This 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).
network This stage is executed when network is available
reconcile This stage is executed 5m after boot and periodically each 60m.
after-install This stage is executed after installation of the OS has ended
after-install-chroot This stage is executed after installation of the OS has ended.
after-upgrade This stage is executed after upgrade of the OS has ended.
after-upgrade-chroot This stage is executed after upgrade of the OS has ended (chroot call).
after-reset This stage is executed after reset of the OS has ended.
after-reset-chroot This stage is executed after reset of the OS has ended (chroot call).
before-install This stage is executed before installation
before-upgrade This stage is executed before upgrade
before-reset This 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.

Sentinels

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:


Last modified November 13, 2022: :book: Use hugo/docsy for docs (#414) (3eec237)