Air-Gap Install
You can install K3s in an air-gapped environment using two different methods. An air-gapped environment is any environment that is not directly connected to the Internet. You can either deploy a private registry and mirror docker.io, or you can manually deploy images such as for small clusters.
Load Images
Private Registry Method
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
- Obtain the images archive for your architecture from the releases page for the version of K3s you will be running.
- Use
docker image load k3s-airgap-images-amd64.tar.zst
to import images from the tar file into docker. - Use
docker tag
anddocker push
to retag and push the loaded images to your private registry. - Follow the Private Registry Configuration guide to create and configure the
registries.yaml
file. - Proceed to the Install K3s section below.
Manually Deploy Images Method
These steps assume you have already created nodes in your air-gap environment, are using the bundled containerd as the container runtime, and cannot or do not want to use a private registry.
This method requires you to manually deploy the necessary images to each node, and is appropriate for edge deployments where running a private registry is not practical.
Prepare the Images Directory and Airgap Image Tarball
- Obtain the images archive for your architecture from the releases page for the version of K3s you will be running.
- Download the images archive to the agent's images directory, for example:
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo curl -L -O /var/lib/rancher/k3s/agent/images/k3s-airgap-images-amd64.tar.zst https://github.com/k3s-io/k3s/releases/download/v1.29.1-rc2%2Bk3s1/k3s-airgap-images-amd64.tar.zst
- Proceed to the Install K3s section below.
Embedded Registry Mirror
The Embedded Registry Mirror is available as an experimental feature as of January 2024 releases: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1
K3s includes an embedded distributed OCI-compliant registry mirror. When enabled and properly configured, images available in the containerd image store on any node can be pulled by other cluster members without access to an external image registry.
The mirrored images may be sourced from an upstream registry, registry mirror, or airgap image tarball. For more information on enabling the embedded distributed registry mirror, see the Embedded Registry Mirror documentation.
Install K3s
Prerequisites
Before installing K3s, complete the Private Registry Method or the Manually Deploy Images Method 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 you intend to deploy K3s with SELinux enabled, you will need also install the appropriate k3s-selinux RPM on all nodes. 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.4.stable.1/k3s-selinux-1.4-1.el8.noarch.rpm
# Transfer RPM to air-gapped machine
On air-gapped machine:
sudo yum install ./k3s-selinux-1.4-1.el8.noarch.rpm
See the SELinux section for more information.
Installing K3s in an Air-Gapped Environment
You can install K3s on one or more servers as described below.
- Single Server Configuration
- High Availability Configuration
To install K3s on a single server, simply do the following on the server node:
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh