Skip to main content

Air-Gap Install

This guide walks you through installing K3s in an air-gapped environment using a three-step process.

1. Load Images​

Each image loading method has different requirements and is suited for different air-gapped scenarios. Choose the method that best fits your infrastructure and security requirements.

These steps assume you have already created nodes in your air-gap environment, are using the bundled containerd as the container runtime, and have a OCI-compliant private registry available in your environment.

If you have not yet set up a private Docker registry, refer to the official Registry documentation.

Create the Registry YAML and Push Images​

  1. Obtain the images archive for your architecture from the releases page for the version of K3s you will be running.
  2. Use docker image load k3s-airgap-images-amd64.tar.zst to import images from the tar file into docker.
  3. Use docker tag and docker push to retag and push the loaded images to your private registry.
  4. Follow the Private Registry Configuration guide to create and configure the registries.yaml file.
  5. Proceed to the Install K3s section below.

2. Install K3s​

Prerequisites​

Before installing K3s, choose one of the Load Images options above to prepopulate the images that K3s needs to install.

Binaries​

  • Download the K3s binary from the releases page, matching the same version used to get the airgap images. Place the binary in /usr/local/bin on each air-gapped node and ensure it is executable.
  • Download the K3s install script at get.k3s.io. Place the install script anywhere on each air-gapped node, and name it install.sh.

Default Network Route​

If your nodes do not have an interface with a default route, a default route must be configured; even a black-hole route via a dummy interface will suffice. K3s requires a default route in order to auto-detect the node's primary IP, and for kube-proxy ClusterIP routing to function properly. To add a dummy route, do the following:

ip link add dummy0 type dummy
ip link set dummy0 up
ip addr add 203.0.113.254/31 dev dummy0
ip route add default via 203.0.113.255 dev dummy0 metric 1000

When running the K3s script with the INSTALL_K3S_SKIP_DOWNLOAD environment variable, K3s will use the local version of the script and binary.

SELinux RPM​

If running on an air-gapped node with SELinux enabled, you must manually install the k3s-selinux RPM before installing K3s. This RPM includes the necessary SELinux policies for K3s to run properly. The latest version of the RPM can be found here. For example, on CentOS 8:

# On internet accessible machine:
curl -LO https://github.com/k3s-io/k3s-selinux/releases/download/v1.6.stable.1/k3s-selinux-1.6-1.el8.noarch.rpm

# Transfer RPM to air-gapped machine
sudo yum install ./k3s-selinux-1.6-1.el8.noarch.rpm

The k3s-selinux RPM installation requires the following dependencies to be available in the OS:

  • container-selinux
  • policycoreutils
  • selinux-policy

See the SELinux section for more information.

Running Install Script​

You can install K3s on one or more servers as described below.

To install K3s on a single server, simply do the following on the server node:

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

To add additional agents, do the following on each agent node:

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://<SERVER_IP>:6443 K3S_TOKEN=<YOUR_TOKEN> ./install.sh
note

K3s's --resolv-conf flag is passed through to the kubelet, which may help with configuring pod DNS resolution in air-gap networks where the host does not have upstream nameservers configured.

3. Upgrading​

Upgrading an air-gap environment can be accomplished in the following manner:

  1. Download the new air-gap images (tar file) from the releases page for the version of K3s you will be upgrading to. Place the tar in the /var/lib/rancher/k3s/agent/images/ directory on each node. Delete the old tar file.
  2. Copy and replace the old K3s binary in /usr/local/bin on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
  3. Restart the K3s service (if not restarted automatically by installer).