Version: v1.9

Rancher Air-Gap Installation

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

You can follow the Rancher Air-Gapped Helm CLI Install to install Rancher in Air-Gapped environment.

Best Practice

Setup a private registry server to host the container images used by Rancher.
```
#!/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
```
note
It is recommended to reserve at least 100GB disk space for the registry server to store Rancher images.

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.
Download the Rancher image list file rancher-images.txt from Rancher GitHub Release page.

We use version v2.7.9 in this example.
```
wget 'https://github.com/rancher/rancher/releases/download/v2.7.9/rancher-images.txt'
```
The rancher-images.txt image list file contains both rancher core, charts, Kontainer Driver Metadata images (RKE, RKE2 and K3s images).

In this example, we use cert-manager to generate the HTTPS certificate for Rancher, refer to the Rancher Collect the cert-manager image instruction to collect the cert-manager images into rancher-images.txt image list file.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm fetch jetstack/cert-manager --version v1.11.0
helm template ./cert-manager-v1.11.0.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt

If the server has public internet connection, use hangar mirror command to mirror both amd64 and arm64 container images from public registry server to your private image registry.

#!/bin/bash

hangar mirror \
    -f 'rancher-images.txt' \
    -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 'rancher-images.txt' \
    -d 'localhost:5000' \
    --arch 'amd64,arm64' \
    --os 'linux' \
    --jobs 5 \
    --tls-verify=false

If the server does not have public internet connection, use hangar save and hangar load command to copy container images to the private registry server.

#!/bin/bash

# Save images into rancher-images.zip.
# Run these commands on a internet accessible machine.
hangar save \
    -f 'rancher-images.txt' \
    -d 'rancher-images.zip' \
    --arch 'amd64,arm64' \
    --os 'linux' \
    --jobs 5

# Validate the saved images if necessary.
hangar save validate \
    -f 'rancher-images.txt' \
    -d 'rancher-images.zip' \
    --arch 'amd64,arm64' \
    --os 'linux' \
    --jobs 5

note

You need to reserve enough disk space when downloading all images of Rancher. The size of the saved archive file may larger than 50GB.

It is recommended to reserve at least 80GB disk space.

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

#!/bin/bash

# Load images from rancher-images.zip to the private image registry server.
# Run these commands on air-gapped machine.
hangar load \
    -s 'rancher-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 'rancher-images.zip' \
    -d 'localhost:5000' \
    --arch 'amd64,arm64' \
    --os 'linux' \
    --jobs 5 \
    --tls-verify=false

After setup the private image registry server used by Rancher, you can use this registry server to run RKE, RKE2 or K3s Kubernetes clusters.

In this example, we use K3s version v1.26.8+k3s1 to prepare the Kurbernetes cluster used by Rancher.

The rancher image list file rancher-images.txt already contains K3s images, you do not need to copy K3s images into your private image registry again.

Create the /etc/rancher/k3s/registries.yaml configuration file by refer to K3s Private 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/k3s
```
/etc/rancher/k3s/registries.yaml
```
mirrors:
    docker.io:
        endpoint:
        - "http://registry.example.com:5000"
    "registry.example.com:5000":
        endpoint:
        - "http://registry.example.com:5000"
```
Download the K3s install.sh install script and binary file by refer to the guide of Air Gap install K3s, then install K3s.
```
export INSTALL_K3S_SKIP_DOWNLOAD=true
export INSTALL_K3S_EXEC="--system-default-registry=registry.example.com:5000"

./install.sh
```
You also need to install kubectl and helm command line tools before installing Rancher.

You can execute following command to pull images from the private image registry server to ensure that the registries.yaml config is working properly:

k3s crictl pull registry.example.com:5000/rancher/mirrored-pause:3.6

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

$ sudo k3s crictl images
IMAGE                                                        TAG                    IMAGE ID            SIZE
registry.example.com:5000/rancher/klipper-helm               v0.8.2-build20230815   5f89cb8137ccb       90.9MB
registry.example.com:5000/rancher/local-path-provisioner     v0.0.24                b29384aeb4b13       14.9MB
......

Install Rancher on K3s cluster by refer to the Rancher Air-Gapped Installation instruction page.

note

In this example, we assume that the IP address of rancher server was bind to the URL rancher.example.com.

Apply the cert-manager CRD and then install cert-manager Helm Chart.

#!/bin/bash

kubectl create namespace cert-manager
kubectl apply -f cert-manager-crd.yaml

helm install cert-manager ./cert-manager-v1.11.0.tgz \
    --namespace 'cert-manager' \
    --set image.repository='registry.example.com:5000/jetstack/cert-manager-controller' \
    --set webhook.image.repository='registry.example.com:5000/jetstack/cert-manager-webhook' \
    --set cainjector.image.repository='registry.example.com:5000/jetstack/cert-manager-cainjector' \
    --set startupapicheck.image.repository='registry.example.com:5000/jetstack/cert-manager-ctl'

Then Download the Rancher Helm Chart file and install Rancher via Helm CLI.

#!/bin/bash

kubectl create namespace cattle-system

helm install rancher ./rancher-2.7.9.tgz \
    --namespace cattle-system \
    --set replicas=1 \
    --set bootstrapPassword="RancherForFun" \
    --set hostname="rancher.example.com" \
    --set rancherImage="registry.example.com:5000/rancher/rancher" \
    --set systemDefaultRegistry="registry.example.com:5000" \
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

Visit the rancher hostname (in this example is rancher.example.com) to access Rancher.

The bootstrap password in this example is RancherForFun.

Best Practice​

Best Practice