Version: v1.9

K3s Air-Gapped Installation

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

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

Best Practice

Setup a private registry server to host the container images used by K3s.
```
#!/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.
Download the K3s image list file from K3s GitHub Release page.

We use version v1.27.6+k3s1 in this example.
```
wget 'https://github.com/k3s-io/k3s/releases/download/v1.27.6%2Bk3s1/k3s-images.txt'
```

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 'k3s-images.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 'k3s-images.txt' \
    -s 'docker.io' \
    -d 'localhost:5000' \
    --arch 'amd64,arm64' \
    --os 'linux' \
    --jobs 5 \
    --tls-verify=false

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

#!/bin/bash

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

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

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

#!/bin/bash

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

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 installation script install.sh and K3s binary file by refer to Air Gap install K3s, then install K3s server.

export INSTALL_K3S_SKIP_DOWNLOAD=true
export INSTALL_K3S_EXEC="--system-default-registry=registry.example.com:5000"

./install.sh

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

# Check the K3s systemd service status
systemctl status k3s

# View all pods of the K3s cluster
k3s kubectl get pods -A

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

Best Practice​

Best Practice