Skip to main content
Version: v2.0-v2.4

Upgrading Rancher Installed on Kubernetes with Helm 2

Helm 3 has been released. If you are using Helm 2, we recommend migrating to Helm 3 because it is simpler to use and more secure than Helm 2.

The current instructions for Upgrading Rancher Installed on Kubernetes use Helm 3.

This section provides a copy of the older instructions for upgrading Rancher with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

The following instructions will guide you through using Helm to upgrade a Rancher server that is installed on a Kubernetes cluster.

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

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

Notes:

Prerequisites

  • 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 GitHub and on the Rancher forums.
  • For air gap installs only, collect and populate images for the new Rancher server version. Follow the guide to populate your private registry with the images for the Rancher version that you want to upgrade to.

Upgrade Outline

Follow the steps to upgrade Rancher server:

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

Take a one-time snapshot of your Kubernetes cluster running Rancher server. You'll use the snapshot as a restore point if something goes wrong during upgrade.

B. Update the Helm chart repository

  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.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      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>

    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.

  1. 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

C. 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.

helm get values rancher

hostname: rancher.my.org

Note: There will be more values that are listed with this command. This is just an example of one of the values.

If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher. Otherwise, follow Option A: Upgrading Rancher.

Option A: Upgrading Rancher

Upgrade Rancher to the latest version with all your settings.

Take all the values from the previous step and append them to the command using --set key=value. Note: There will be many more options from the previous step that need to be appended.

helm upgrade --install rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org
Option B: Reinstalling Rancher chart

If you are currently running the cert-manager 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-manager due to the API change in cert-manager v0.11.

  1. Uninstall Rancher

    helm delete rancher

    In case this results in an error that the release "rancher" was not found, make sure you are using the correct deployment name. Use helm list to list the helm-deployed releases.

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

  3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using --set key=value. Note: There will be many more options from the step 1 that need to be appended.

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

D. Verify the Upgrade

Log 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 roll back instructions to restore the snapshot you took before you preformed the upgrade.