Air-Gapped Installation

Install k3s on machines with no internet access using the binary and a bundled images archive.

SyntaxINSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

An air-gapped environment has no internet access. k3s supports this well because it ships its system images as a downloadable archive.

The pieces you need

  1. The k3s binary for your architecture.
  2. The k3s-airgap-images-<arch>.tar archive from the GitHub release.
  3. The install script (run with INSTALL_K3S_SKIP_DOWNLOAD=true).

Place the images archive in /var/lib/rancher/k3s/agent/images/ and k3s will import it on startup instead of pulling from the internet.

Example

Example · bash
# On the offline machine, after copying the files across
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar \
  /var/lib/rancher/k3s/agent/images/

sudo cp k3s /usr/local/bin/k3s
sudo chmod +x /usr/local/bin/k3s

# Run the install script without downloading anything
sudo INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

When to use it

  • A government facility installs k3s on air-gapped servers by transferring the binary and images tarball via USB drive.
  • A ship's onboard computer cluster receives a k3s offline bundle during port visits, then operates autonomously at sea.
  • A manufacturing plant deploys k3s on machines isolated from the public internet using a pre-pulled images archive for compliance reasons.

More examples

Download artifacts on a connected host

Downloads the k3s binary and the bundled images archive on an internet-connected machine for transfer to the air-gapped host.

Example · bash
VERSION=v1.29.3+k3s1
wget https://github.com/k3s-io/k3s/releases/download/${VERSION}/k3s
wget https://github.com/k3s-io/k3s/releases/download/${VERSION}/k3s-airgap-images-amd64.tar.gz

Prepare the offline images

Places the images tarball where k3s expects it and installs the binary so the air-gapped install can proceed.

Example · bash
mkdir -p /var/lib/rancher/k3s/agent/images/
cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/
chmod +x k3s && mv k3s /usr/local/bin/

Run air-gapped install script

Runs a local copy of the install script with SKIP_DOWNLOAD so it uses the pre-placed binary and images instead of fetching them.

Example · bash
INSTALL_K3S_SKIP_DOWNLOAD=true \
  INSTALL_K3S_EXEC='--node-ip 192.168.10.5' \
  ./install.sh
kubectl get nodes

Related

k3s private registryk3s requirements

Discussion

  • Be the first to comment on this lesson.