Version: 2.4.15

Choosing a Rancher Version

This section describes how to choose a Rancher version.

For a high-availability installation of Rancher, which is recommended for production, the Rancher server is installed using a Helm chart on a Kubernetes cluster. Refer to the Helm version requirements to choose a version of Helm to install Rancher.

For Docker installations of Rancher, which is used for development and testing, you will install Rancher as a Docker image.

When installing, upgrading, or rolling back Rancher Server when it is installed on a Kubernetes cluster, Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.

Refer to the Helm version requirements to choose a version of Helm to install Rancher.

Helm Chart Repositories#

Rancher provides several different Helm chart repositories to choose from. We align our latest and stable Helm chart repositories with the Docker tags that are used for a Docker installation. Therefore, the rancher-latest repository will contain charts for all the Rancher versions that have been tagged as rancher/rancher:latest. When a Rancher version has been promoted to the rancher/rancher:stable, it will get added to the rancher-stable repository.

Type	Command to Add the Repo	Description of the Repo
rancher-latest	`helm repo add rancher-latest https://releases.rancher.com/server-charts/latest`	Adds a repository of Helm charts for the latest versions of Rancher. We recommend using this repo for testing out new Rancher builds.
rancher-stable	`helm repo add rancher-stable https://releases.rancher.com/server-charts/stable`	Adds a repository of Helm charts for older, stable versions of Rancher. We recommend using this repo for production environments.
rancher-alpha	`helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha`	Adds a repository of Helm charts for alpha versions of Rancher for previewing upcoming releases. These releases are discouraged in production environments. Upgrades to or from charts in the rancher-alpha repository to any other chart, regardless or repository, aren't supported.

Instructions on when to select these repos are available below in Switching to a Different Helm Chart Repository.

> Note: All charts in the rancher-stable repository will correspond with any Rancher version tagged as stable.

Helm Chart Versions#

Rancher Helm chart versions match the Rancher version (i.e appVersion). Once you've added the repo you can search it to show available versions with the following command: helm search repo --versions

If you have several repos you can specify the repo name, ie. helm search repo rancher-stable/rancher --versions For more information, see https://helm.sh/docs/helm/helm_search_repo/

To fetch a specific version of your chosen repo, define the --version parameter like in the following example: helm fetch rancher-stable/rancher --version=2.4.8

Switching to a Different Helm Chart Repository#

After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps.

> Note: Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported.

List the current Helm chart repositories.

helm repo list
NAME                  URLstable                https://charts.helm.sh/stablerancher-\<CHART_REPO\>      https://releases.rancher.com/server-charts/\<CHART_REPO\>

Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be rancher-stable or rancher-latest depending on what you had initially added.
```
helm repo remove rancher-\<CHART_REPO\>
```

Add the Helm chart repository that you want to start installing Rancher from.

helm repo add rancher-\<CHART_REPO\> https://releases.rancher.com/server-charts/\<CHART_REPO\>

Continue to follow the steps to upgrade Rancher from the new Helm chart repository. {{% /tab %}} {{% tab "Docker Images" %}} When performing Docker installs, upgrades, or rollbacks, you can use tags to install a specific version of Rancher.

Server Tags#

Rancher Server is distributed as a Docker image, which have tags attached to them. You can specify this tag when entering the command to deploy Rancher. Remember that if you use a tag without an explicit version (like latest or stable), you must explicitly pull a new version of that image tag. Otherwise, any image cached on the host will be used.

Tag	Description
`rancher/rancher:latest`	Our latest development release. These builds are validated through our CI automation framework. These releases are not recommended for production environments.
`rancher/rancher:stable`	Our newest stable release. This tag is recommended for production.
`rancher/rancher:\<v2.X.X\>`	You can install specific versions of Rancher by using the tag from a previous release. See what's available at DockerHub.

> Notes: > > - The master tag or any tag with -rc or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported. > - Want to install an alpha review for preview? Install using one of the alpha tags listed on our announcements page (e.g., v2.2.0-alpha1). Caveat: Alpha releases cannot be upgraded to or from any other release.