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

This document (000020159) is provided subject to the disclaimer at the end of this document.



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


This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

  • Document ID:000020159
  • Creation Date: 06-May-2021
  • Modified Date:06-May-2021
    • SUSE Rancher

< Back to Support Search

For questions or concerns with the SUSE Knowledgebase please contact: tidfeedback[at]

SUSE Support Forums

Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

Join Our Community

Support Resources

Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.

SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
Support FAQ

Open an Incident

Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

Go to Customer Center