Rancher’s air-gapped installation is surprisingly flexible, allowing you to bypass the need for internet access by mirroring all required container images locally.
Let’s say you’re setting up a Rancher management server in a highly secure, offline environment. You’ve got your air-gapped cluster ready, but Rancher needs its container images. Instead of pointing to registry.rancher.com, you’ll be pulling from your own private registry.
Here’s a typical scenario:
# rancher-cluster.yml (example snippet)
...
privateCA: |-
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
kubeconfig-exclude-args: []
add-local: true
cluster-cidr: 10.42.0.0/16
service-cidr: 10.43.0.0/16
cloudProvider:
name: ""
addons: |
---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
name: rancher
namespace: kube-system
spec:
chart:
repo: https://releases.rancher.com/charts/latest
name: rancher
version: 2.7.9
valuesContent: |-
hostname: rancher.mydomain.com
ingress:
tls:
Source: secret
privateCA: |-
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
replicas: 3
resources: {}
auditLog:
enabled: true
level: "3"
systemDefaultRegistry: "my.private.registry.local:5000"
authProxy:
proxy: "my.private.registry.local:5000"
whitelist:
- "my.private.registry.local:5000"
...
This valuesContent snippet is key. Notice systemDefaultRegistry, authProxy, and whitelist. These tell Rancher where to find its images when it can’t reach the public internet. You’re essentially creating a local mirror of the official Rancher registry.
The core problem Rancher’s air-gapped installation solves is enabling Kubernetes deployments in environments with strict network isolation. Without internet access, the Kubernetes nodes cannot pull container images from public registries like Docker Hub or registry.rancher.com. Rancher’s air-gapped mode addresses this by providing a mechanism to host all necessary images on a private, internal registry that your Kubernetes nodes can access.
Internally, Rancher’s installation process is designed to be adaptable. When you specify a systemDefaultRegistry, Rancher modifies the Helm chart values it uses to deploy its components. Instead of using image tags like registry.rancher.com/rancher/rancher:v2.7.9, it prefixes them with your private registry address, transforming them into my.private.registry.local:5000/rancher/rancher:v2.7.9. This redirection happens at the Kubernetes level, specifically within the Pod definitions and Helm chart configurations that Rancher manages.
The exact levers you control are primarily within the values.yaml file (or equivalent configuration for your chosen installation method) for the Rancher Helm chart. The most critical parameters are:
systemDefaultRegistry: This is the primary endpoint for all Rancher-related images. It must be reachable by all Kubernetes nodes.authProxy: For Rancher’s internal authentication and authorization proxy, which also needs to be accessible.whitelist: This is a crucial security feature. It specifies which registries are considered "trusted" or allowed for image pulling. You must include your private registry here.privateCA: If your private registry uses a self-signed or internal CA certificate, you’ll need to provide the certificate here so Kubernetes can trust the connection.
The one thing most people don’t realize is that the whitelist parameter isn’t just for Rancher’s own components; it also influences how Kubernetes itself pulls images for any workload you deploy through Rancher if you’re using the air-gapped configuration. If a deployment attempts to pull from a registry not listed in the whitelist, Kubernetes will reject the pull, even if the registry is otherwise accessible and configured in systemDefaultRegistry.
Once your Rancher management server is up and running in an air-gapped environment using your mirrored images, the next hurdle you’ll likely face is enabling your managed Kubernetes clusters to also pull their operating system and application images from your private registry.