Illumina Innovates with Rancher and Kubernetes
The following instructions will guide you through using Helm to upgrade a high-availability (HA) Rancher server installation.
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.
Note: 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.
Review the Known Upgrade Issues and Caveats
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.
Follow the steps to upgrade Rancher server:
Take a one-time snapshot of your Kubernetes cluster running Rancher server. You’ll use the snapshot as a restoration point if something goes wrong during upgrade.
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.
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://kubernetes-charts.storage.googleapis.com 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 .tgz file.
.tgz
helm fetch rancher-<CHART_REPO>/rancher
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
Get the values, that were passed with --set, from the current Rancher helm chart installed.
--set
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.
Upgrade Rancher to the latest version with all your settings.
--set key=value
helm upgrade rancher rancher-<CHART_REPO>/rancher \ --set hostname=rancher.my.org # Note: There will be many more options from the previous step that need to be appended.
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.
<VERSION>
<RANCHER.YOURDOMAIN.COM>
<REGISTRY.YOURDOMAIN.COM:PORT>
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 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
Note: If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret.
--set privateCA=true
--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 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
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.
kubectl
kubectl -n cattle-system apply -R -f ./rancher
Log into Rancher to confirm that the upgrade succeeded.
Having network issues following upgrade? See Restoring Cluster Networking.
Having network issues following upgrade?
See Restoring Cluster Networking.
Should something go wrong, follow the roll back instructions to restore the snapshot you took before you preformed the upgrade.