These instructions assume you have already followed the instructions for a Kubernetes upgrade on this page, including the prerequisites, up until step 3. Upgrade Rancher.

Rancher Helm Template Options

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.

PlaceholderDescription
<VERSION>The version number of the output tarball.
<RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
<REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
<CERTMANAGER_VERSION>Cert-manager version running on k8s cluster.

Option A: Default Self-signed Certificate

  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2.     --no-hooks \ # prevent files for Helm hooks from being generated
  3.     --namespace cattle-system \
  4.     --set hostname=<RANCHER.YOURDOMAIN.COM> \
  5.     --set certmanager.version=<CERTMANAGER_VERSION> \
  6.     --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  7.     --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  8.     --set useBundledSystemChart=true # Use the packaged Rancher system charts
  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2.  --namespace cattle-system \
  3.  --set hostname=<RANCHER.YOURDOMAIN.COM> \
  4.  --set certmanager.version=<CERTMANAGER_VERSION> \
  5.  --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  6.  --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  7.  --set useBundledSystemChart=true # Use the packaged Rancher system charts

Option B: Certificates from Files using Kubernetes Secrets

  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2.     --no-hooks \ # prevent files for Helm hooks from being generated
  3.     --namespace cattle-system \
  4.     --set hostname=<RANCHER.YOURDOMAIN.COM> \
  5.     --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  6.     --set ingress.tls.source=secret \
  7.     --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  8.     --set useBundledSystemChart=true # 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:

  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2.     --no-hooks \ # prevent files for Helm hooks from being generated
  3.     --namespace cattle-system \
  4.     --set hostname=<RANCHER.YOURDOMAIN.COM> \
  5.     --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  6.     --set ingress.tls.source=secret \
  7.     --set privateCA=true \
  8.     --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  9.     --set useBundledSystemChart=true # Use the packaged Rancher system charts
  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2. --namespace cattle-system \
  3. --set hostname=<RANCHER.YOURDOMAIN.COM> \
  4. --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  5. --set ingress.tls.source=secret \
  6. --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  7. --set useBundledSystemChart=true # 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:

  1. helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
  2. --namespace cattle-system \
  3. --set hostname=<RANCHER.YOURDOMAIN.COM> \
  4. --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  5. --set ingress.tls.source=secret \
  6. --set privateCA=true \
  7. --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
  8. --set useBundledSystemChart=true # Use the packaged Rancher system charts

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.

  1. kubectl -n cattle-system apply -R -f ./rancher

Verify the Upgrade

Log into Rancher to confirm that the upgrade succeeded.

Having network issues following upgrade?

See Restoring Cluster Networking.

Known Upgrade Issues

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