How to Create an Airgap K3s Installation with Kairos

This section describe examples on how to use AuroraBoot and Kairos bundles to create ISOs for airgapped installs

If you want to create an airgap K3s installation, Kairos provides a convenient way to do so using AuroraBoot. In this guide, we will go through the process of creating a custom ISO of Kairos that contains a configuration file and a bundle that executes preparatory steps after installation. The bundle will overlay new files in the system and prepare the node for having an airgapped K3s installation.


Docker running in the host

Creating the Bundle

First, we need to create a bundle that contains the K3s images used for the airgap installation. The bundle will place the images in the /var/lib/rancher/k3s/agent/images directory. The /var/lib/rancher is already configured as persistent by Kairos defaults and every change to that directory persist reboots. You can add additional persistent paths in the system with the cloud config

  1. Create a new directory named images-bundle, and create a new file inside it called Dockerfile.
  2. Paste the following code into the Dockerfile:
FROM alpine AS alpine
WORKDIR /build
RUN wget

FROM scratch
COPY ./ /
COPY --from=alpine /build/k3s-airgap-images-amd64.tar.gz /assets
  1. Create a new file called inside the images-bundle directory, and paste the following code:

mkdir -p /usr/local/.state/var-lib-rancher.bind/k3s/agent/images/
cp -rfv ./k3s-airgap-images-amd64.tar.gz /usr/local/.state/var-lib-rancher.bind/k3s/agent/images/
  1. Make the file executable by running the following command:
chmod +x
  1. Build the container image by running the following command inside the images-bundle directory. This will save the image as data/bundle.tar:
docker build -t images-bundle .
  1. Save the bundle:
$ ls

# create a directory
$ mkdir data
$ docker save images-bundle -o data/bundle.tar

Building the Offline ISO for Airgap

Now that we have created the bundle, we can use it to build an offline ISO for the airgap installation.

  1. Create a cloud config for the ISO and save it as config.yaml. The config.yaml file should contain your cloud configuration for Kairos and is used to set up the system when it is installed. An example can be:

 auto: true
 device: "auto"
 reboot: true
  # This bundle needs to run after-install as it consumes assets from the LiveCD
  # which is not accessible otherwise at the first boot (there is no live-cd with any bundle.tar)
 - targets:
   - run:///run/initramfs/live/bundle.tar
   local_file: true

# Define the user accounts on the node.
- name: "kairos"                       # The username for the user.
  passwd: "kairos"                      # The password for the user.
  ssh_authorized_keys:                  # A list of SSH keys to add to the user's authorized keys.
  - github:mudler                       # A key from the user's GitHub account.

  enabled: true
  1. Build the ISO with AuroraBoot by running the following command:

docker pull $IMAGE

docker run -v $PWD/config.yaml:/config.yaml \
             -v $PWD/build:/tmp/auroraboot \
             -v /var/run/docker.sock:/var/run/docker.sock \
             -v $PWD/data:/tmp/data \
             --rm -ti \
             --set "disable_http_server=true" \
             --set "disable_netboot=true" \
             --set "container_image=docker://$IMAGE" \
             --set "" \
             --cloud-config /config.yaml \
             --set "state_dir=/tmp/auroraboot"

The resulting ISO should be available at: build/iso/kairos.iso

This example is also available in the AuroraBoot repository in the examples/airgap directory, where you can run to reproduce the example.

See also

Last modified February 23, 2024: Reduce sizes and remove warnings (0e183ae)