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 (https://github.com/rancher/rancher/releases/tag/v2.0.0), the needed scripts for this scenario are provided. You will need the following:
- rancher-save-images.sh: 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.
- rancher-load-images.sh: This script will load images from
rancher-images.tar.gzand push them to your private registry. You have to supply the hostname of your private registry as first argument to the script.
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 (https://github.com/rancher/rancher/releases/tag/v2.0.0). 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
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.
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
docker run -d -p 80:80 -p 443:443 -e CATTLE_SYSTEM_DEFAULT_REGISTRY=registry.yourdomain.com:5000 registry.yourdomain.com:5000/rancher/rancher:v2.0.0
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
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
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.
Click Next to create the cluster
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.
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
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
Registries to configure your registry used for workloads.
Fill in the needed information to access your 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 https://slack.rancher.io and join the #2-0-tech-preview channel. You can also visit our forums to ask any questions you may have: https://forums.rancher.com/
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 (https://slack.rancher.io) if you have any questions.