Configuration

#cloud-config

# Additional system users
users:
- name: "kairos"
  passwd: "kairos"
  lock_passwd: true
  groups: [ "admin" ]
  # ssh_authorized_keys:
  # - github:mudler

# enable debug logging
debug: true
# Additional paths for look for cloud-init files
cloud-init-paths:
  - "/some/path"
# fail on cloud-init errors, defaults to false
strict: false

# The install block is to drive automatic installations without user interaction.
install:
  # Device for automated installs
  # This can be either a full device path (so /dev/sda) or you can use the udev facility to identify the disk by UUID, path, label, diskseq or id (/dev/disk/by-{uuid,label,path,diskseq})
  # Note that to use a disk by UUID or label, it has first to have that added from userspace, for example with `mkfs.ext4 -L LABEL -U UUID /dev/sda` otherwise disks dont come with UUID/label if they are empty
  device: "/dev/sda"
  # Reboot after installation
  reboot: true
  # Power off after installation
  poweroff: true
  # Set to true when installing without Pairing
  auto: true

  # Override the grub entry name
  grub-entry-name: Kairos
  
  # partitions setup
  # setting a partition size key to 0 means that the partition will take over the rest of the free space on the disk
  # after creating the rest of the partitions
  # by default the persistent partition has a value of 0
  # if you want any of the extra partitions to fill the rest of the space, you will need to set the persistent partition
  # size to a different value, for example
  # partitions:
  #   persistent:
  #     size: 300

  # default partitions
  # only 'oem', 'recovery', 'state' and 'persistent' objects allowed
  # Only size and fs should be changed here
  # size in MiB
  partitions:
    oem:
      size: 60
      fs: ext4
    recovery:
      size: 4096
      fs: ext4
  # note: This can also be set with dot notation like the following examples for a more condensed view:
  # partitions.oem.size: 60
  # partitions.oem.fs: ext4
  # partitions.recovery.size: 4096
  # partitions.recovery.fs: ext4

  # extra partitions to create during install
  # only size, label and fs are used
  # name is used for the partition label, but it's not really used during the kairos lifecycle. No spaces allowed.
  # if no fs is given the partition will be created but not formatted
  # These partitions are not automounted only created and formatted
  extra-partitions:
    - name: myPartition
      size: 100
      fs: ext4
      label: ONE_PARTITION
    - name: myOtherPartition
      size: 200
      fs: ext4
      label: TWO_PARTITION
  
  # no-format: true skips any disk partitioning and formatting
  # If set to true installation procedure will error out if expected
  # partitions are not already present within the disk.
  no-format: false

  # if no-format is used and elemental is running over an existing deployment
  # force can be used to force installation.
  force: false

  # Creates these dirs in the rootfs during installation. As the rootfs is RO from boot, sometimes we find that we
  # some applications want to write to non-standard paths like /data
  # If that dir is not already in the rootfs it makes it difficult to create that path on an RO system
  # This allows to create some extra paths in the rootfs that then we count use for mounting or binding via
  # the cloud-config stages
  extra-dirs-rootfs:
    - /data
    - /src
  
  # Override image sizes for active/passive/recovery
  # Note that the active+passive images are stored in the state partition and
  # the recovery in the recovery partition, so they should be big enough to accommodate te images sizes set below
  # size in MiB
  system:
    size: 4096
  passive:
    size: 4096
  recovery-system:
    size: 5000
  # note: This can also be set with dot notation like the following examples for a more condensed view:
  # system.size: 4096
  # passive.size: 4096
  # recovery-system.size: 5000
  
  # Use a different container image for the installation
  source: "docker:.."
  # Add bundles in runtime
  bundles:
    - ...
  # Set grub options
  grub_options:
    # additional Kernel option cmdline to apply
    extra_cmdline: "config_url=http://"
    # Same, just for active
    extra_active_cmdline: ""
    # Same, just for passive
    extra_passive_cmdline: ""
    # Change GRUB menu entry
    default_menu_entry: ""
  # Environmental variable to set to the installer calls
  env:
  - foo=bar
  # custom user mounts
  # bind mounts, can be read and modified, changes persist reboots
  bind_mounts:
  - /mnt/bind1
  - /mnt/bind2
  # ephemeral mounts, can be read and modified, changed are discarded at reboot
  ephemeral_mounts:

# The reset block configures what happens when reset is called
reset:
  # Reboot after reset
  reboot: true
  # Power off after reset
  poweroff: true

  # Override the grub entry name
  grub-entry-name: Kairos

  # if set to true it will format persistent partitions ('oem 'and 'persistent')
  reset-persistent: true
  reset-oem: false

  # Creates these dirs in the rootfs during reset. As the rootfs is RO from boot, sometimes we find that we
  # some applications want to write to non-standard paths like /data
  # If that dir is not already in the rootfs it makes it difficult to create that path on an RO system
  # This allows to create some extra paths in the rootfs that then we count use for mounting or binding via
  # the cloud-config stages
  extra-dirs-rootfs:
    - /data
    - /src


# The upgrade block configures what happens when upgrade is called
upgrade:
  # Reboot after upgrade
  reboot: true
  # Power off after upgrade
  poweroff: true

  # Override the grub entry name
  grub-entry-name: Kairos

  # if set to true upgrade command will upgrade recovery system instead
  # of main active system
  recovery: false

  # Override image sizes for active/recovery
  # Note that the active+passive images are stored in the state partition and
  # the recovery in the recovery partition, so they should be big enough to accommodate te images sizes set below
  # size in MiB
  # During upgrade only the active or recovery image cna be resized as those are the ones that contain the upgrade
  # passive image is the current system, and that its untouched during the upgrade
  system:
    size: 4096
  recovery-system:
    size: 5000

  # Creates these dirs in the rootfs during upgrade. As the rootfs is RO from boot, sometimes we find that we
  # some applications want to write to non-standard paths like /data
  # If that dir is not already in the rootfs it makes it difficult to create that path on an RO system
  # This allows to create some extra paths in the rootfs that then we count use for mounting or binding via
  # the cloud-config stages
  extra-dirs-rootfs:
    - /data
    - /src


k3s:
  # Additional env/args for k3s server instances
  env:
    K3S_RESOLV_CONF: ""
    K3S_DATASTORE_ENDPOINT: "mysql://username:password@tcp(hostname:3306)/database-name"
  args:
    - --node-label ""
    - --data-dir ""
  # Enabling below it replaces args/env entirely
  # replace_env: true
  # replace_args: true

k3s-agent:
  # Additional env/args for k3s agent instances
  env:
    K3S_NODE_NAME: "foo"
  args:
    - --private-registry "..."
  # Enabling below it replaces args/env entirely
  # replace_env: true
  # replace_args: true

# The p2p block enables the p2p full-mesh functionalities.
# To disable, don't specify one.
p2p:
  # Manually set node role. Available: master, worker. Defaults auto (none). This is available
 role: "master"
  # User defined network-id. Can be used to have multiple clusters in the same network
 network_id: "dev"
  # Enable embedded DNS See also: https://mudler.github.io/edgevpn/docs/concepts/overview/dns/
 dns: true
 # Disabling DHT makes co-ordination to discover nodes only in the local network
 disable_dht: true #Enabled by default
 # Configures a VPN for the cluster nodes
 vpn:
   create: false # defaults to true
   use: false # defaults to true
   env:
    # EdgeVPN environment options
    DHCP: "true"
    # Disable DHT (for airgap)
    EDGEVPNDHT: "false"
    EDGEVPNMAXCONNS: "200"
    # If DHCP is false, it's required to be given a specific node IP. Can be arbitrary
    ADDRESS: "10.2.0.30/24"
    # See all EDGEVPN options:
    # - https://github.com/mudler/edgevpn/blob/master/cmd/util.go#L33
    # - https://github.com/mudler/edgevpn/blob/master/cmd/main.go#L48
 # Automatic cluster deployment configuration
 auto:
   # Enables Automatic node configuration (self-coordination)
   # for role assignment
   enable: true
   # HA enables automatic HA roles assignment.
   # A master cluster init is always required,
   # Any additional master_node is configured as part of the 
   # HA control plane.
   # If auto is disabled, HA has no effect.
   ha:
     # Enables HA control-plane
     enable: true
     # Number of HA additional master nodes.
     # A master node is always required for creating the cluster and is implied.
     # The setting below adds 2 additional master nodes, for a total of 3.
     master_nodes: 2
     # Use an External database for the HA control plane
     external_db: "external-db-string"
 # network_token is the shared secret used by the nodes to co-ordinate with p2p
 network_token: "YOUR_TOKEN_GOES_HERE"

## Sets the Elastic IP used in KubeVIP. Only valid with p2p
kubevip:
  eip: "192.168.1.110"
  # Specify a manifest URL for KubeVIP. Empty uses default
  manifest_url: ""
  # Enables KubeVIP
  enable: true
  # Specifies a KubeVIP Interface
  interface: "ens18"

# Additional cloud init syntax can be used here.
# See `stages` below.
stages:
  network:
    - name: "Setup users"
      authorized_keys:
        kairos:
          - github:mudler

# Standard cloud-init syntax, see: https://github.com/mudler/yip/tree/e688612df3b6f24dba8102f63a76e48db49606b2#compatibility-with-cloud-init-format
growpart:
 devices: ['/']


runcmd:
- foo
hostname: "bar"
write_files:
- encoding: b64
  content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4
  path: /foo/bar
  permissions: "0644"
  owner: "bar"

#cloud-config

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

# List the YAML files in your current directory
$ ls -liah
total 4,0K
9935 drwxr-xr-x.  2 itxaka itxaka  60 may 17 11:21 .
   1 drwxrwxrwt. 31 root   root   900 may 17 11:28 ..
9939 -rw-r--r--.  1 itxaka itxaka  59 may 17 11:21 00_test.yaml

$ cat 00_test.yaml
stages:
  initramfs:
    - commands:
      - echo "hello!"


# Run the cloud-init command on your YAML files in a Docker container
$ docker run -ti -v $PWD:/test --entrypoint /usr/bin/kairos-agent --rm quay.io/kairos/ubuntu:24.04-core-amd64-generic-v3.2.4 run-stage --cloud-init-paths /test initramfs

# Output from the run-stage command
INFO[2023-05-17T11:32:09+02:00] kairos-agent version 0.0.0                   
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs.before              
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs.before'      
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs                     
INFO[2023-05-17T11:32:09+02:00] Processing stage step ''. ( commands: 1, files: 0, ... ) 
INFO[2023-05-17T11:32:09+02:00] Command output: hello!                       
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs'             
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs.after               
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs.after'       
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs.before              
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs.before'      
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs                     
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs'             
INFO[2023-05-17T11:32:09+02:00] Running stage: initramfs.after               
INFO[2023-05-17T11:32:09+02:00] Done executing stage 'initramfs.after'          

#cloud-config
users:
  - name: 007

kairos validate ./cloud-config.yaml
jsonschema: '/users/0/name' does not validate with file:///home/mauro/workspace/kairos/schema.json#/properties/users/items/$ref/properties/name/type: expected string, but got number

#cloud-config

stages:
  foo:
  - name: "echo"
    commands:
    - echo "{{.Values.node.hostname}}"

#cloud-config

stages:
  initramfs:
    - name: "Setup hostname"
      hostname: "node-{{ trunc 4 .MachineID }}"

#cloud-config

install:
  grub_options:
    extra_cmdline: "panic=0"

name: "Deploy fleet out of the box"
stages:
  boot:
    - name: "Copy fleet deployment files"
      files:
        - path: /var/lib/rancher/k3s/server/manifests/fleet-config.yaml
          content: |
            apiVersion: v1
            kind: Namespace
            metadata:
              name: cattle-system
            ---
            apiVersion: helm.cattle.io/v1
            kind: HelmChart
            metadata:
              name: fleet-crd
              namespace: cattle-system
            spec:
              chart: https://github.com/rancher/fleet/releases/download/v0.3.8/fleet-crd-0.3.8.tgz
            ---
            apiVersion: helm.cattle.io/v1
            kind: HelmChart
            metadata:
              name: fleet
              namespace: cattle-system
            spec:
              chart: https://github.com/rancher/fleet/releases/download/v0.3.8/fleet-0.3.8.tgz            

#cloud-config
install:
  device: /dev/sda
k3s:
  enabled: true

users:
- name: "kairos"
  passwd: "kairos"
  ssh_authorized_keys:
  - github:mudler
- name: "testuser"
  passwd: "testuser"
  ssh_authorized_keys:
  - github:mudler
  groups:
  - "admin"

stages:
   initramfs:
     - name: "Set user and password"
       users:
        testuser:
          groups:
          - "admin"
          passwd: "mypassword"
          shell: /bin/bash
          homedir: "/home/testuser"

❯ ssh testuser@192.168.1.238
testuser@192.168.1.238's password:
Welcome to kairos!

Refer to https://kairos.io for documentation.
localhost:~$ sudo su -
localhost:~# whoami
root
localhost:~# exit
localhost:~$ whoami
testuser
localhost:~$

curl -X POST http://localhost:8080/api/dns --header "Content-Type: application/json" -d '{ "Regex": "foo.bar", "Records": { "A": "2.2.2.2" } }'

#cloud-config
p2p:
  network_token: "...."
  # Enable embedded DNS See also: https://mudler.github.io/edgevpn/docs/concepts/overview/dns/
  dns: true
  vpn:
    env:
      # Disable DNS forwarding
      DNSFORWARD: "false"
      # Set cache size
      DNSCACHESIZE: "200"
      # Set DNS forward server
      DNSFORWARDSERVER: "8.8.8.8:53"

#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:
        providers:
          - "digitalocean"
          - "aws"
          - "gcp"
        path: "/usr/local/etc"

#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 ]"

#cloud-config

stages:
  foo:
  - name: "echo"
    commands:
    - echo hello
    node: "the_node_hostname_here" # Node hostname

#cloud-config

stages:
  foo:
  - name: "echo"
    commands:
    - echo hello
    if: "cat /proc/cmdline | grep debug"

name: "Test yip!"

#cloud-config

stages:
   boot:
     - name: "Setup logging"
       node: "bastion"

#cloud-config
stages:
  boot.after:
    - name: "do something"
      commands:
        - bash /path/to/script.sh