Skip to main content
Version: v2.5

2. Collect and Publish Images to your Private Registry

This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.

By default, all images used to provision Kubernetes clusters or launch any tools in Rancher, e.g. monitoring and logging, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.

Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.

The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any downstream Kubernetes clusters using Windows nodes, there are separate instructions to support the images needed.

Prerequisites:

You must have a private registry available to use.

If the registry has certs, follow this K3s documentation about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.

For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.

  1. Find the required assets for your Rancher version
  2. Collect the cert-manager image (unless you are bringing your own certificates or terminating TLS on a load balancer)
  3. Save the images to your workstation
  4. Populate the private registry

Prerequisites​

These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.

If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.

1. Find the required assets for your Rancher version​

  1. Go to our releases page, find the Rancher v2.x.x release that you want to install, and click Assets. Note: Don't use releases marked rc or Pre-release, as they are not stable for production environments.

  2. From the release's Assets section, download the following files, which are required to install Rancher in an air gap environment:

Release FileDescription
rancher-images.txtThis file contains a list of images needed to install Rancher, provision clusters and user Rancher tools.
rancher-save-images.shThis script pulls all the images in the rancher-images.txt from Docker Hub and saves all of the images as rancher-images.tar.gz.
rancher-load-images.shThis script loads images from the rancher-images.tar.gz file and pushes them to your private registry.

2. Collect the cert-manager image​

Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.

In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the cert-manager image to rancher-images.txt as well.

  1. Fetch the latest cert-manager Helm chart and parse the template for image details:

    Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

    helm repo add jetstack https://charts.jetstack.io
    helm repo update
    helm fetch jetstack/cert-manager --version v1.5.1
    helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt

  2. Sort and unique the images list to remove any overlap between the sources:

    sort -u rancher-images.txt -o rancher-images.txt

3. Save the images to your workstation​

  1. Make rancher-save-images.sh an executable:

    chmod +x rancher-save-images.sh

  2. Run rancher-save-images.sh with the rancher-images.txt image list to create a tarball of all the required images:

    ./rancher-save-images.sh --image-list ./rancher-images.txt

    Result: Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named rancher-images.tar.gz. Check that the output is in the directory.

4. Populate the private registry​

Next, you will move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

Move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

The rancher-images.txt is expected to be on the workstation in the same directory that you are running the rancher-load-images.sh script. The rancher-images.tar.gz should also be in the same directory.

  1. Log into your private registry if required:

    docker login <REGISTRY.YOURDOMAIN.COM:PORT>

  2. Make rancher-load-images.sh an executable:

    chmod +x rancher-load-images.sh

  3. Use rancher-load-images.sh to extract, tag and push rancher-images.txt and rancher-images.tar.gz to your private registry:

    ./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>

Next step for Kubernetes Installs - Launch a Kubernetes Cluster​

Next step for Docker Installs - Install Rancher​