Procedure for Rancher Update - Advises / Approval Needed

SUSE Rancher Prime
1

Hi Suse / Rancher community !

Here is my situation:

I have few experience on Rancher and K3S.
I have a K3S cluster v1.28.15+3s1 running on Rancher v.2.8.3 and Helm v2.16.8.

I need to update to K3S v1.31 but it is not listed by Rancher Manager.

From my understanding I need to update to Helm3 and update Rancher before updating K3S.

I made a procedure to follow based on Rancher Docs, Jim’s Garage Video and ChatGPT.

Can you (the Rancher community) tell me if the procedure below is good before I try it on my lab?
All advises are welcome. I hope it will also help other newbie like me.

Regards.
Foreman21

1) Check version of Rancher certified for Kubernetes v1.31
https://www.suse.com/suse-rancher/support-matrix/
In my case it is 2.10.X, so updating to last version is recommended (04-2025).

2) Check OS Compatibility with K3S version
https://www.suse.com/suse-k3s/support-matrix/all-supported-versions
If OS not listed do a distro-upgrate of each node. Check Rancher docs…

3) Do VM backups or snapshot of Rancher node, Master nodes, Worker nodes
See your Hypervisor procedure.

4) Upgrade Helm

# Check current Helm version
helm version

# If Helm is not v3, download and install the latest version
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify Helm is updated
helm version
#Should be latest version of 2.10.X

5) Upgrade Rancher

# Add or update the Rancher Helm chart repository
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
helm repo update

# List available Rancher chart versions
helm search repo rancher-latest/rancher

# Upgrade Rancher to the latest available version
helm upgrade rancher rancher-latest/rancher \
  --namespace cattle-system

# Wait for the Rancher deployment to become ready
kubectl -n cattle-system rollout status deploy/rancher

6) Update K3S

Go to Rancher webui.

Go to Cluster Management → edit config of cluster that must be update.

Go to K3S Options → Kubernetes Version then select newer version of K3S.

Click on save. Kubernetes begins upgrading for the cluster.

SOURCES:

Upgrade Rancher: https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades

Upgrade Kubernetes: https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes

Jim’s Garage: https://www.youtube.com/watch?v=h0s2YHPzHb8

ChatGPT

2

@Foreman21 Your thought process and steps are mostly correct. Just want to clarify specifically on version upgrades for rancher/k3s/rke2.

On step 5 of upgrading Rancher, it is not supported jumping from v2.8.3 directly to 2.10.x. You want to step upgrade all the stable minor releases from each major version and then upgrade to the next major release. IE go from your v2.8.3 to 2.8.4 to 2.8.5, then upgrade to v2.9.1 in sequence to v2.9.3 the highest stable release. Then jump to v2.10.1 to v2.10.3.

On step 6, While you do each minor/major upgrade of v2.8/2.9/2.10. See what K8s versions are available and then follow the same K8s recommended upgrade path. In your case you are on the latest 1.28 version v1.28.15+k3s1. Once you reach v2.9.1 you can upgrade k3s version to 1.29. Then do minor upgrades until you can major upgrade to 1.30, etc.

Last tip, also track the Rancher local cluster k8s version and upgrade that as well before upgrading rancher and make sure you are on a supported k8s version. You can upgrade the local cluster from the web ui similar to DS clusters.

Good luck on your upgrades!

3

A few questions:

Are you using Rancher Prime (i.e. the paid for version) or “community” Rancher?
Which type and version of Kubernetes is hosting your Rancher?

4

That’s not quite correct as you do not need to go through each minor release for a major version so you can go from 2.8.3 to latest applicable* 2.8.x then to latest applicable 2.9.x to latest 2.10.x

*I say latest applicable because the latest will depend on whether using Rancher Prime or “community” Rancher

1 Like
5

Good to know, thanks! Where I work we only used community and always made sure to upgrade each minor on release.

6

Hi smflood, meza

I appreciate your help.

I am using the community edition. I hope I am in the right section of this forum.

Here is some correction on my current configuration:

Rancher is running on a dedicated VM using K3S on v1.28.8+k3s1
and the cluster I want to update to v1.31 is running on v1.28.15+k3s1

Does that mean I must:

  1. first update rancher to 2.8.14 (latest of 2.8.X)
  2. then to 2.9.8 (latest of 2.9.x) and update local k3s cluster that host Rancher to v1.30
  3. finaly update rancher to 2.10.4 (current of 2.10.x) and update local Rancher cluster to v1.31

Is it correct ?

Regarding the cluster I want to update, does it need to be updated right after each update of rancher local cluster update? Or can I, after I updated to 2.10.4 and v1.31, directly update it from v1.28.15 to v1.31?

Regards.

7

Hi !

There are some points I think understood from your answers:

  • Version of kubernetes cluster, local and other must be supported in the support matrix of Rancher version.
  • We can’t update Rancher to a version that do not support cluster(s) current version kubernetes. It is because rancher must be updated before kubernetes cluster.
  • We must upgrade Rancher with each next major release, up to target version.
    Example: 2.8.x to 2.9x before going to 2.10.x.
  • At each Rancher next major release, upgrade all clusters to latest version of kubernetes supported. This avoid having kerbernetes supported version issue after Rancher upgrade.
  • We must update kubernetes of local cluster that run Rancher before updating other clusters.

Tell me if I am wrong.

Here is updated procedures I will follow.

1) Check version of Rancher certified for Kubernetes v1.31
https://www.suse.com/suse-rancher/support-matrix/
In my case it is 2.10.X, so updating to last version is recommended (04-2025).

2) Check OS Compatibility with K3S version
https://www.suse.com/suse-k3s/support-matrix/all-supported-versions
If OS not listed do a distro-upgrate of each node. Check Rancher docs…

3) Do VM backups or snapshot of Rancher node, Master nodes, Worker nodes
See your Hypervisor procedure.

4) Upgrade Helm

# Check current Helm version
helm version

# If Helm is not v3, download and install the latest version
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify Helm is updated
helm version
#Should be latest version of 2.10.X

5) Upgrade Rancher to 2.8.14

# Add or update the Rancher Helm chart repository
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
helm repo update

# List available Rancher chart versions
helm search repo rancher-latest/rancher

# Upgrade Rancher  to version 2.8.14
helm upgrade rancher rancher-latest/rancher \
  --version 2.8.14 \
  --namespace cattle-system

# Wait for the Rancher deployment to become ready
kubectl -n cattle-system rollout status deploy/rancher

6) Update local K3S to v1.28.15+k3s1

Go to Rancher webui.

Go to Cluster Management → edit config of cluster that must be update.

Go to K3S Options → K3S Version to v1.28.15+k3s1.

Click on save. Kubernetes begins upgrading for the cluster.

7) Upgrade Rancher to 2.9.8

# Upgrade Rancher to version 2.9.8
helm upgrade rancher rancher-latest/rancher \
  --version 2.9.8 \
  --namespace cattle-system

# Wait for the Rancher deployment to become ready
kubectl -n cattle-system rollout status deploy/rancher

8) Update K3S to v1.30

First update local cluster to v1.30
Then update each other cluster, one by one, to v1.30

9) Upgrade Rancher to 2.10.4

# Upgrade Rancher to version 2.10.4
helm upgrade rancher rancher-latest/rancher \
  --version 2.10.4 \
  --namespace cattle-system

# Wait for the Rancher deployment to become ready
kubectl -n cattle-system rollout status deploy/rancher

10) Update K3S to v1.31

First update local cluster to v1.31
Then update each other cluster, one by one, to v1.31

Enjoy :slight_smile:

8

Community releases are limited to the first few minor releases for each major version (before the next major version is released) so you can never upgrade with all minor releases unless you have Prime and even then it would keep you busy!

9

The Community bit is important as I’ll note below and whilst this section of the forum is titled “SUSE Rancher Prime” there isn’t a non-Prime Community section so yes I’d say you’re in the right place. The alternative would be the Rancher Users Slack channel but I find that’s more for very specific questions and issues.

Since you are using the Community edition that limits the Rancher versions that you can use.

You have Rancher 2.8.3 and want to manage K3s 1.3.1 but to do that you need Rancher 2.10.x - see the Rancher Support Matrix at https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-10-1/

So how to get there? First you need to upgrade Rancher to 2.8.5 as the last Community release of Rancher 2.8.x (2.8.6 was first Prime-only release of 2.8.x). Then to 2.9.3 as last Community release of 2.9.x (2.9.4 was first Prime-only release of 2.9.x). Then to 2.10.3 as, you guessed it, last Community release of 2.10.x (2.10.4 was first Prime-only release of 2.10.x).

With that done you can upgrade your K3s cluster from 1.28.15 to 1.31 but via 1.29 and then 1.30 as it’s not supported to jump major versions.

Ditto with your Rancher hosting K3s although it supported to run Rancher 2.10.x on K3s 1.28.x but that will change with Rancher 2.11.x.

How did you originally install your K3s clusters as you should use the same way(s) to upgrade them?