For the instructions to upgrade Rancher installed on Kubernetes with RancherD, refer to

For the instructions to upgrade Rancher installed with Docker, refer to this page.

To upgrade the components in your Kubernetes cluster, or the definition of the or add-ons, refer to the , the Rancher Kubernetes Engine.

If you installed Rancher using the RKE Add-on yaml, follow the directions to migrate or upgrade.

• Upgrade Outline
• RKE Add-on Installs

Prerequisites

Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.

If you installed Kubernetes with RKE, the config will have been created in the directory you ran in.

The kubeconfig can also be manually targeted for the intended cluster with the --kubeconfig tag (see: https://helm.sh/docs/helm/helm/)

Review Known Issues

Review the known upgrade issues in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.

A more complete list of known issues for each Rancher version can be found in the release notes on and on the Rancher forums.

Note that upgrades to or from any chart in the aren’t supported.

Helm Version

The upgrade instructions assume you are using Helm 3.

For migration of installs started with Helm 2, refer to the official The Helm 2 upgrade page hereprovides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

For air gap installs: Populate private registry

-For air gap installs only, collect and populate images for the new Rancher server version. Follow the guide to with the images for the Rancher version that you want to upgrade to.

If you are upgrading to Rancher v2.5 from a Rancher server that was started with the Helm chart option --add-local=false, you will need to drop that flag when upgrading. Otherwise, the Rancher server will not start. The restricted-admin role can be used to continue restricting access to the local cluster. For more information, see this section.

For upgrades from v2.0-v2.2 with external TLS termination

If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to enable using forwarded host headers.

For upgrades with cert-manager older than 0.8.0

Let’s Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019. Upgrade cert-manager to the latest version by following

Upgrade Outline

Follow the steps to upgrade Rancher server:

• 3. Upgrade Rancher

1. Back up Your Kubernetes Cluster that is Running Rancher Server

For Rancher v2.0-v2.4, of your Kubernetes cluster running Rancher server.

You’ll use the backup as a restoration point if something goes wrong during upgrade.

2. Update the Helm chart repository

1. Update your local helm repo cache.

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

   For information about the repos and their differences, see .

   Latest: Recommended for trying out the newest features

   Stable: Recommended for production environments

   Alpha: Experimental preview of upcoming releases.
   Note: Upgrades are not supported to, from, or between Alphas.

   helm repo list
   NAME                   URL
   stable                 https://charts.helm.sh/stable
   rancher-<CHART_REPO>     https://releases.rancher.com/server-charts/<CHART_REPO>

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

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

   helm fetch rancher-<CHART_REPO>/rancher

   You can fetch the chart for the specific version you are upgrading to by adding in the --version= tag. For example:

   helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11

3. Upgrade Rancher

This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.

Get the values, which were passed with --set, from the current Rancher Helm chart that is installed.

If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow

Otherwise, follow Option A: Upgrading Rancher.

Option A: Upgrading Rancher

Take all the values from the previous step and append them to the command using --set key=value:

helm upgrade rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org

Alternatively, it’s possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:

helm get values rancher -n cattle-system -o yaml > values.yaml
  --namespace cattle-system \
  -f values.yaml \
  --version=2.4.5

If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manger due to the API change in cert-manger v0.11.

1. Uninstall Rancher

   helm delete rancher -n cattle-system

2. Uninstall and reinstall cert-manager according to the instructions on the Upgrading Cert-Manager page.

Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

Based on the choice you made during installation, complete one of the procedures below.

Option A: Default Self-signed Certificate

helm template ./rancher-<VERSION>.tgz --output-dir . \
 --name rancher \
 --namespace cattle-system \
 --set hostname=<RANCHER.YOURDOMAIN.COM> \
 --set certmanager.version=<CERTMANAGER_VERSION> \
 --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
 --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
 --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

Option B: Certificates from Files using Kubernetes Secrets

helm template ./rancher-<VERSION>.tgz --output-dir . \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set privateCA=true \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher

Apply the Rendered Templates

Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.

Use kubectl to apply the rendered manifests.

4. Verify the Upgrade

Log into Rancher to confirm that the upgrade succeeded.

Known Upgrade Issues

The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on GitHub and on the

RKE Add-on Installs

Important: RKE add-on install is only supported up to Rancher v2.0.8

If you are currently using the RKE add-on install method, see for details on how to move to using the helm chart.