RKE2 Air-Gap Installation

This example will guide you to setup a multi-arch private image registry server for RKE2 Air-Gapped installation.

You can use the RKE2 Private Registry Method to prepare the private image registry server used by RKE2.

Best Practice

1. Setup a private registry server to host the container images used by RKE2.

   #!/bin/bash
   
   # In this example, we create a directory to store the container image layers.
   mkdir -p registry
   
   docker run -d \
       -p 5000:5000 \
       -v $(pwd)/registry:/var/lib/registry \
       --name registry \
       registry:2

   Login to the private image registry.

   hangar login 'localhost:5000' --tls-verify=false
   note

   By default, the registry server can be login with any username and password.

   You can configure the authentication config of the registry server by refer to Distribution Registry Token Authentication and setup the HTTPS certificate to use in production.

2. Download the RKE2 image list file from RKE2 GitHub Release page.

   We use version v1.27.7+rke2r1 in this example.

   # Download the AMD64 image list file
   wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-amd64.txt'
   
   # Download the ARM64 image list file
   wget 'https://github.com/rancher/rke2/releases/download/v1.27.7%2Brke2r1/rke2-images-all.linux-arm64.txt'

   You can use following command to merge amd64 and arm64 image list into one file if you need to run RKE2 on both amd64 and arm64 architectures.

   sort rke2-images-all.linux-*.txt | uniq > rke2-images-all.linux.txt

3. If the server has the ability to access Docker Hub registry server (with internet connection), use Hangar mirror command to mirror both amd64 and arm64 container images from Docker Hub to your private image registry.

   #!/bin/bash
   
   hangar mirror \
       -f 'rke2-images-all.linux.txt' \
       -s 'docker.io' \
       -d 'localhost:5000' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5 \
       --tls-verify=false

   Use the Hangar mirror validate command to verify the copied container images if necessary.

   #!/bin/bash
   
   hangar mirror validate \
       -f 'rke2-images-all.linux.txt' \
       -s 'docker.io' \
       -d 'localhost:5000' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5 \
       --tls-verify=false

4. If the server can't access Docker Hub (without internet connection), use hangar save and hangar load command to copy container image to the private registry server.

   #!/bin/bash
   
   # Save images into rke2-images.zip.
   # Run these commands on a internet accessible machine.
   hangar save \
       -f 'rke2-images-all.linux.txt' \
       -s 'docker.io' \
       -d 'rke2-images.zip' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5
   
   # Validate the saved images if necessary.
   hangar save validate \
       -f 'rke2-images-all.linux.txt' \
       -s 'docker.io' \
       -d 'rke2-images.zip' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5

   The saved rke2-images.zip archive file contains both amd64 and arm64 container images.

   #!/bin/bash
   
   # Load images from rke2-images.zip to the private image registry server.
   # Run these commands on air-gapped machine.
   hangar load \
       -s 'rke2-images.zip' \
       -d 'localhost:5000' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5 \
       --tls-verify=false
   
   # Validate the loaded images if necessary.
   hangar load validate \
       -s 'rke2-images.zip' \
       -d 'localhost:5000' \
       --arch 'amd64,arm64' \
       --os 'linux' \
       --jobs 5 \
       --tls-verify=false

5. Create the /etc/rancher/rke2/registries.yaml configuration file by refer to RKE2 Containerd Registry Configuration.

   note

   In this example, we assume that the private image registry IP address was bind to the URL registry.example.com.

   mkdir -p /etc/rancher/rke2
   /etc/rancher/rke2/registries.yaml

   mirrors:
       docker.io:
           endpoint:
           - "http://registry.example.com:5000"
       "registry.example.com:5000":
           endpoint:
           - "http://registry.example.com:5000"

6. Install RKE2 by refer to the guide of RKE2 Air-Gap Install.

   Configure the RKE2 system default registry to registry.example.com.

   /etc/rancher/rke2/config.yaml

   system-default-registry: "registry.example.com:5000"

   You can use following commands to view the status of RKE2 server.

   # Check the RKE2 systemd service status
   systemctl status rke2-server
   
   # View all pods of the RKE2 cluster
   # The default kube config file is /etc/rancher/rke2/rke2.yaml.
   export KUBECONFIG="/etc/rancher/rke2/rke2.yaml"
   kubectl get pods -A

7. After install and launch RKE2 server, you can execute following command to pull images from the private image registry server to ensure that the registries.yaml config is working properly:

   sudo /var/lib/rancher/rke2/bin/crictl \
       --config "/var/lib/rancher/rke2/agent/etc/crictl.yaml" \
       pull registry.example.com:5000/rancher/mirrored-pause:3.6

   Use following command to view pulled images from the private image registry:

   $ sudo /var/lib/rancher/rke2/bin/crictl --config "/var/lib/rancher/rke2/agent/etc/crictl.yaml" images
   IMAGE                                                   TAG                            IMAGE ID            SIZE
   registry.example.com:5000/rancher/hardened-calico       v3.26.1-build20230802          a0e7293895577       195MB
   registry.example.com:5000/rancher/hardened-etcd         v3.5.9-k3s1-build20230802      c6b7a4f2f79b2       64.4MB
   ......