You are viewing the development docs which are in progress. There is no guarantee that the development documentation will be accurate, including instructions, links, and other information. For the latest stable documentation, click here.

Pushing configuration to a node after installation

Kairos configuration mechanism is based on the cloud-config file given during installation, however, it’s possible to extend the configuration by providing additional cloud-configs in either /oem or /usr/local/cloud-config.

By default, kairos reads in lexicographic order YAML cloud-config files in the directories above, indeed, after installation you should be able to see the configuration generated by the interactive-installer as /oem/99_custom.yaml in the system.

This mechanism can be used to set and enable persistent configuration on boot after node deployment.

We are going to see how to do that manually or with Kubernetes by using the Kairos operator.

Manually

SSH into the node and copy the config file you want to add into /oem. For instance, to add zram on boot we can copy the following file in /oem/100_zram.yaml or /usr/local/cloud-config/100_zram.yaml and reboot:

stages:
  boot:
    - name: "zram setup"
      commands:
        - modprobe zram
        - echo lzo > /sys/block/zram0/comp_algorithm
        - echo 1G > /sys/block/zram0/disksize
        - mkswap --label zram0 /dev/zram0
        - swapon --priority 100 /dev/zram0
name: "zfs setup"

With Kubernetes

To push configurations to a node, it is recommended to use the Kairos operator which provides a more integrated approach for managing Kairos nodes. In the example below, we use a NodeOp to push a swapfile configuration and restart the node afterward.

Note

The Kairos operator provides several deployment strategies that can be configured through the NodeOp resource. You can control concurrency, node selection, and failure handling. The example below shows a simple approach where the operation is applied to every host of the cluster, one-by-one in sequence.

The following pushes a new cloud config over the /oem directory and reboots the node:

apiVersion: operator.kairos.io/v1alpha1
kind: NodeOp
metadata:
  name: add-swapfile
  namespace: default
spec:
  # NodeSelector to target specific nodes
  nodeSelector:
    matchLabels:
      kairos.io/managed: "true"

  # The container image to use
  image: quay.io/kairos/@flavor

  # Custom command to execute
  command:
    - sh
    - -c
    - |
      set -e

      # Create swapfile configuration
      cat > /host/oem/10_swapfile.yaml << 'EOF'
      stages:
       boot:
         - name: "Setup swapfile"
           if: "[ ! -e /usr/local/swapfile ]"
           commands:
           - dd if=/dev/zero of=/usr/local/swapfile bs=1M count=3K
           - mkswap /usr/local/swapfile
         - name: "Enable swapfile"
           if: "[ -e /usr/local/swapfile ]"
           commands:
           - swapon /usr/local/swapfile
      EOF

      sync
      # Note: The reboot is handled automatically by the operator when rebootOnSuccess: true      

  # Path where the node's root filesystem will be mounted
  hostMountPath: /host

  # Whether to cordon the node before running the operation
  cordon: true

  # Drain options for pod eviction
  drainOptions:
    enabled: true
    force: false
    gracePeriodSeconds: 30
    ignoreDaemonSets: true
    deleteEmptyDirData: false
    timeoutSeconds: 300

  # Whether to reboot the node after successful operation
  rebootOnSuccess: true

  # Maximum number of nodes that can run the operation simultaneously
  concurrency: 1

  # Whether to stop creating new jobs when a job fails
  stopOnFailure: true

Last modified July 25, 2025: Replace system-upgrade-controller with the kairos operator (#445) (2483c15)