How to switch from private mirror to bundled system-charts in Rancher v2.3 and v2.4

Table of Contents


The Rancher system-charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS.

In air gapped installations prior to Rancher v2.3.0 it was necessary to host a private mirror of this repository. However, since v2.3.0 a copy of these charts has been bundled with the Rancher image.

This article outlines how to switch from using a private mirror to the bundled system-charts that are included in the Rancher v2.3 and v2.4 images, removing the requirement to host a private mirror.


  • A Rancher v2.3.x or v2.4.x instance, provisioned as a Highly Available (HA) install on a Kubernetes cluster, or running as a Single Node install using Docker.


Rancher HA Install

For a Rancher HA install this follows the same steps as the upgrade documentation.

  1. Get your current helm deployment values with helm get values rancher. Example output:

    helm get values rancher
  2. Append --set useBundledSystemChart=true to your values, set the --version value to your current Rancher version, e.g. 2.4.2, (to pin the version and prevent an actual upgrade) and run the helm upgrade command. Example:

    helm upgrade rancher rancher-stable/rancher \
    --namespace cattle-system \
    --set \
    --set useBundledSystemChart=true \
    --version 2.4.2

At this point your HA Rancher should be using the bundled charts for the system-charts.

Rancher Single Node Install Using Docker

To accomplish this for single node installations using Docker, you will be re-creating the Rancher container, with its current data, to add the CATTLE_SYSTEM_CATALOG=bundled environment variable. This closely follows the upgrade documentation.

  1. Create a copy of the data from your Rancher server container. <RANCHER_CONTAINER_NAME> is the name of your container as shown with docker ps and the <RANCHER_CONTAINER_TAG> is the version of Rancher (v2.3.0 for example):

    docker stop <RANCHER_CONTAINER_NAME>
    docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
  2. Create a backup tarball:

    docker run --volumes-from rancher-data -v $PWD:/backup busybox tar zcvf /backup rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
  3. Start a new Rancher container with the added environment variable. The important thing to note here is that you use all of the same flags as when you initially started Rancher and append -e CATTLE_SYSTEM_CATALOG=bundled before the Rancher image. Example:

    docker run -d --volumes-from rancher-data \
    --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -e CATTLE_SYSTEM_CATALOG=bundled \

At this point your single node Rancher installation using Docker should be using the bundled charts for the system-charts.

Further reading

Documentation on Setting up Local System Charts for Air Gapped Installations

Documentation for Rancher HA Installs

Rancher HA Upgrade Documentation

Rancher HA Helm Chart Options Documentation

Documentation for Single Node Installs

Rancher Single Node Upgrade Documentation

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.