The following instructions will guide you through upgrading a high-availability Rancher Server installed in an air gap environment.


  • Populate Images

    Follow the guide to Prepare the Private Registry with the images for the upgrade Rancher release.

  • Backup your Rancher Cluster

    Take a one-time snapshot of your Rancher Server cluster. You’ll use the snapshot as a restoration point if something goes wrong during upgrade.

  • kubectl

    Follow the kubectl configuration instructions and confirm that you can connect to the Kubernetes cluster running Rancher server.

  • helm

    Install or update Helm to the latest version.

  • Upgrades to v2.0.7+ only: check system namespace locations
    Starting in v2.0.7, Rancher introduced the system project, which is a project that’s automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they’re unassigned to prevent cluster networking issues.

  • Upgrades to v2.2.0 only: mirror system-charts repository and configure Rancher
    Starting in v2.2.0, Rancher introduced the System Charts repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the system-charts repository locally and configure Rancher to use that repository. Please follow the instructions to configure Rancher system charts.


Upgrades to or from any chart in the rancher-alpha repository aren’t supported.

Upgrade Rancher

  1. Update your local helm repo cache.

    helm repo update
  2. Get the repository name that you used to install Rancher.

    For information about the repos and their differences, see Helm Chart Repositories.

    helm repo list
    NAME                  URL

    Note: If you want to switch to a different Helm chart repository, please follow the steps on how to switch repositories. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.

  3. Fetch the latest chart to install Rancher from the Helm chart repository.

    This command will pull down the latest chart and save it in the current directory as a .tgz file.

    helm fetch rancher-<CHART_REPO>/rancher
  4. Render the upgrade template.

    Use the same --set values that you used for the install. Remember to set the --is-upgrade flag for helm. This will create a rancher directory with the Kubernetes manifest files.

    helm template ./rancher-<version>.tgz --output-dir . --is-upgrade \
    --name rancher --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher
  5. Copy and apply the rendered manifests.

    Copy the files to a server with access to the Rancher server cluster and apply the rendered templates.

    kubectl -n cattle-system apply -R -f ./rancher

Result: Rancher is upgraded. Log back into Rancher to confirm that the upgrade succeeded.

Having Network Issues Following Upgrade?

See Restoring Cluster Networking.

Rolling Back

Should something go wrong, follow the HA Rollback instructions to restore the snapshot you took before you preformed the upgrade.