The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.
For the instructions to upgrade Rancher installed with Docker, refer to this page.
Access to kubeconfig
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
rke up 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
Note that upgrades to or from any chart in the rancher-alpha repository aren’t supported.
The upgrade instructions assume you are using Helm 3.
For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. 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 populate your private registry with the images for the Rancher version that you want to upgrade to.
For upgrades from a Rancher server with a hidden local cluster
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 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 these instructions.
Follow the steps to upgrade Rancher server:
- 1. Back up your Kubernetes cluster that is running Rancher server
- 2. Update the Helm chart repository
- 3. Upgrade Rancher
- 4. Verify the Upgrade
1. Back up Your Kubernetes Cluster that is Running Rancher Server
Use the backup application to back up Rancher.
You’ll use the backup as a restore point if something goes wrong during upgrade.
2. Update the Helm chart repository
Update your local helm repo cache.
helm repo update
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 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.
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
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.
Air Gap Instructions: If you are installing Rancher in an air gapped environment, skip the rest of this page and render the Helm template by following the instructions on this page.
Get the values, which were passed with
--set, from the current Rancher Helm chart that is installed.
helm get values rancher -n cattle-system 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 and cert-manager.
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
helm upgrade rancher rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org
Note: The above is an example, there may be more values from the previous step that need to be appended.
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 helm upgrade rancher rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ -f values.yaml \ --version=2.4.5
Option B: Reinstalling Rancher and cert-manager
If you are currently running the cert-manager whose version is 1.5 or below, and want to upgrade both Rancher and cert-manager to a new version (1.6+ in the case of cert-manager), then you need to re-install both Rancher and cert-manager due to the API change in cert-manager 1.6. This will also be necessary if you are upgrading from a version of cert manager below 0.11 to a version of cert-manager above 0.11.
New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
Note that if you are below version 1.5 and want to go to 1.7, you should first upgrade to 1.6 as an intermediate step. Follow the cert-manager docs here to do a 1.5 to 1.6 upgrade, and here to then do a 1.6 to 1.7 upgrade. For more details on upgrading cert-manager, refer to our documentation.
helm delete rancher -n cattle-system
Uninstall and reinstall
cert-manageraccording to the instructions on the Upgrading Cert-Manager page.
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 rancher-<CHART_REPO>/rancher \ --namespace cattle-system \ --set hostname=rancher.my.org
4. Verify the Upgrade
Log into Rancher to confirm that the upgrade succeeded.
Having network issues following upgrade?