How to Create an Airgap K3s Installation with Kairos
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.
NoteIf you already have a Kubernetes cluster, you can use the osbuilder controller to generate container images with your additional files already inside.
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
- Create a new directory named
images-bundle, and create a new file inside it called
- Paste the following code into the
FROM alpine AS alpine WORKDIR /build RUN wget https://github.com/k3s-io/k3s/releases/download/v1.23.16%2Bk3s1/k3s-airgap-images-amd64.tar.gz FROM scratch COPY ./run.sh / COPY --from=alpine /build/k3s-airgap-images-amd64.tar.gz /assets
- Create a new file called
images-bundledirectory, and paste the following code:
#!/bin/bash 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/
- Make the
run.shfile executable by running the following command:
chmod +x run.sh
- Build the container image by running the following command inside the images-bundle directory. This will save the image as
docker build -t images-bundle .
- Save the bundle:
$ ls images-bundle # 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.
- 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:
#cloud-config install: auto: true device: "auto" reboot: true bundles: # 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. users: - 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. k3s: enabled: true
- Build the ISO with AuroraBoot by running the following command:
IMAGE=quay.io/kairos/kairos-opensuse-leap:v1.6.1-k3sv1.26.1-k3s1 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 quay.io/kairos/auroraboot:v0.2.5 \ --set "disable_http_server=true" \ --set "disable_netboot=true" \ --set "container_image=docker://$IMAGE" \ --set "iso.data=/tmp/data" \ --cloud-config /config.yaml \ --set "state_dir=/tmp/auroraboot"
The resulting ISO should be available at:
This example is also available in the AuroraBoot repository in the
examples/airgap directory, where you can run
build_docker.sh to reproduce the example.
Was this page helpful?
Awesome! Glad to hear it! Please tell us how we can improve.
Oh snap! Sorry to hear that. Please tell us how we can improve.