Skip to main content

This guide walks you through installing RKE2 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 RKE2 you will be running.
  2. Assuming amd64, use docker image load rke2-images.linux-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 RKE2 section below.

::: Info CNI plugins and vsphere extra images rke2-images.linux-amd64.tar.zst includes images for all CNI plugin options. As an alternative, you can load rke2-images-core.linux-amd64.tar.zst and the CNI plugin specific tarball, e.g. rke2-images-canal.linux-amd64.tar.zst for canal. If enabling the vSphere CPI/CSI charts (--cloud-provider-name=rancher-vsphere), you must also load the rke2-images-vsphere.linux-amd64.tar.zst archive. :::

2. Install RKE2​

Prerequisites​

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

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

SELinux RPM​

If running on an air-gapped node with SELinux enabled, you must manually install the rke2-selinux RPM before installing RKE2. This RPM includes the necessary SELinux policies for RKE2 to run properly. See our RPM Documentation to learn how to obtain the rpm. The rke2-selinux RPM installation requires the following dependencies to be available in the OS:

  • container-selinux
  • iptables-nft
  • libnftnl
  • policycoreutils
  • selinux-policy

Installation​

RKE2 in airgap can be installed using the binary or the install script

Binaries​

  • Download the RKE2 binary file rke2.linux-amd64 from the releases page, matching the same version and architecture used to get the airgap images. Place the binary in /usr/local/bin on each air-gapped node and ensure it is executable.
  • Run the binary with the desired parameters. For example, if using the Private Registry Method, your config file would have the following:
system-default-registry: "registry.example.com:5000"

Note: The system-default-registry parameter must specify only valid RFC 3986 URI authorities, i.e. a host and optional port.

3. Upgrading​

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

  1. Download the new air-gap images (tar files) from the releases page for the version of RKE2 you will be upgrading to. Place the tar in the /var/lib/rancher/rke2/agent/images/ directory on each node. Delete the old tar files.
  2. Follow the steps of the manual upgrade method