How to setup Rancher 2 in an air gapped environment

Sebastiaan van Steenis
Sebastiaan van Steenis
Gray Calendar Icon Published: May 7, 2018
Gray Calendar Icon Updated: January 26, 2021
Expert Training in Kubernetes and Rancher
Join our free online training sessions to learn more about Kubernetes, containers, and Rancher.

It’s sometimes not possible to use hosted services like GKE or AKS, and there are occasions where direct internet access is not possibe (offline/airgapped). In these instances it is still possible to use Rancher to manage your clusters.

In this post we’ll walk through what you need to do when you want to run Rancher 2.0 in an offline/air gapped environment.

Docker Private Registry

Everything Rancher related runs in a container, so a place to store the containers in your environment is the first requirement. For this example we will use the Docker Registry. If you already have a registry in place, you can skip these steps.

Note: In Rancher 2.0, only registries without authentication are supported for getting all images needed to get Rancher 2.0 up and running. This does not affect configurable Registries to be used in Workloads.

To run the Docker Registry, you need to run an instance of the registry:2 image. We’ll be exposing the default port (5000), and mount a host directory to make sure we have enough space (we need at least 8GB) and get proper I/O performance.

docker run -d -p 5000:5000 --restart=always --name registry -v /opt/docker-registry:/var/lib/registry registry:2

Making the Rancher images available

When the registry is setup, you can start syncing the needed images to run Rancher 2.0. For this step, we will go through two scenarios:

  • Scenario 1: You have one host that can access DockerHub to pull and save the images, and a separate host that access your private registry to push the images.
  • Scenario 2: You have one host that can access both DockerHub and your private registry.

Scenario 1: One host that can access DockerHub, separate host that can access private registry

In every release (, the needed scripts for this scenario are provided. You will need the following:

  • This script will pull all needed images from DockerHub, and save all of the images as a compressed file called rancher-images.tar.gz. This file can be transferred to your on-premise host that can access your private registry.
  • This script will load images from rancher-images.tar.gz and push them to your private registry. You have to supply the hostname of your private registry as first argument to the script.

Flow for scenario 1

Scenario 2: One host that can access both DockerHub and private registry

For this scenario, we provide a file called rancher-images.txt in every release ( This file contains every image needed to run Rancher 2.0. This can be tied into any existing automation to sync images you might have, or you can use my scripts/Docker image as shown below

Flow for scenario 2

Configuring Rancher to use the private registry

The last step in the process is to configure Rancher to use the private registry as source to get the images. This can be configured by using the setting system-default-registry in the Settings view.

Settings view

Configuring the setting for use of private registry, do not prefix with https:// or http://

This will make sure that the rancher/rancher-agent container that is used to add nodes to the cluster, will be prefixed with this value. All other images needed will also use this configuration.

If you want to configure the setting when starting the rancher/rancher container, you can use the environment variable CATTLE_SYSTEM_DEFAULT_REGISTRY.


docker run -d -p 80:80 -p 443:443 -e

Creating a cluster

You can access the Rancher 2.0 UI by using the IP of the host the rancher/rancher container is running on. The initial start-up takes about a minute, and on first access you will be prompted to set a password

Set password

Next, you have to configure the URL that nodes will use to contact this Rancher 2 installation. By default, it will show the IP you are using to visit the UI, but if you are using a DNS name or a loadbalancer, you can change this here.

In the Global view, click Add Cluster

Adding a cluster

For this post, you will be creating a Custom cluster without any advanced options. Please refer to the documentation on configuring advanced options on your cluster.

Adding custom cluster called testcluster

Click Next to create the cluster testcluster.

In the next screen, you get a generated command to launch on your nodes that you want to add to the cluster. The image used in this command should automatically be prefixed with your configured private registry.

Adding nodes to your cluster

You can now select what roles you want to use for the node you want to add, and optionally, you can configure the IP’s used for the node. If not specified, it will auto-detect the IP. Please refer to the documentation on the meaning of the Node Roles.

Configuring access to the registry inside a project

As previously mentioned, at this point Rancher 2 does not support using private registry with authentication for images needed to run Rancher 2.0. It does support this scenario for workloads in projects.

To configure your registry with authentication, you can open your project in a cluster (Default is automatically created for you). When you are in the Default project, you can navigate to Resources -> Registries to configure your registry used for workloads.

Configuring Registries in project Default

Click Add Registry

Adding a registry

Fill in the needed information to access your registry.

Providing credentials for registry


I hope the information in this how-to was useful, and that you were able to setup Rancher 2.0 in your environment. I know a lot of environments also have a proxy, and we will add or create separate posts for proxy setups soon. Stay tuned.

I will finish by posting a gist with some commands used in this post; hopefully these will be helpful for use or inspiration.

If you have any questions, join our Rancher Users Slack by visiting and join the #2-0-tech-preview channel. You can also visit our forums to ask any questions you may have:

Sebastiaan van Steenis

Sebastiaan is a support engineer at Rancher Labs, helping customers on their journey with containers. You can find him on Rancher Users Slack ( if you have any questions.

GitHub: superseb

Twitter: @svsteenis

Expert Training in Kubernetes and Rancher
Join our free online training sessions to learn more about Kubernetes, containers, and Rancher.
Sebastiaan van Steenis
Sebastiaan van Steenis
Software Engineer, Rancher
Get started with Rancher