Skip to main content

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, or you can manually deploy images such as for small clusters.

Private Registry Method

This document assumes you have already created your nodes in your air-gap environment and have a Docker private registry on your bastion host.

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

Create the Registry YAML

Follow the Private Registry Configuration guide to create and configure the registry.yaml file.

Once you have completed this, you may now go to the Install K3s section below.

Manually Deploy Images Method

We are assuming you have created your nodes in your air-gap environment and use containerd as container runtime. 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 K3s Binary

Obtain the images tar file for your architecture from the releases page for the version of K3s you will be running.

Place the tar file in the images directory, for example:

sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/

Once you have completed this, you may now go to the Install K3s section below.

Install K3s


Before installing K3s, complete the Private Registry Method or the Manually Deploy Images Method above to prepopulate the images that K3s needs to install.


  • 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 Place the install script anywhere on each air-gapped node, and name it

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 dev dummy0
ip route add default via 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.


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

# 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.

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


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


The token from the server is typically found at /var/lib/rancher/k3s/server/token.


K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.


Install Script Method

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 (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).

Automated Upgrades Method

K3s supports automated upgrades. To enable this in air-gapped environments, you must ensure the required images are available in your private registry.

You will need the version of rancher/k3s-upgrade that corresponds to the version of K3s you intend to upgrade to. Note, the image tag replaces the + in the K3s release with a - because Docker images do not support +.

You will also need the versions of system-upgrade-controller and kubectl that are specified in the system-upgrade-controller manifest YAML that you will deploy. Check for the latest release of the system-upgrade-controller here and download the system-upgrade-controller.yaml to determine the versions you need to push to your private registry. For example, in release v0.4.0 of the system-upgrade-controller, these images are specified in the manifest YAML:


Once you have added the necessary rancher/k3s-upgrade, rancher/system-upgrade-controller, and rancher/kubectl images to your private registry, follow the automated upgrades guide.