How to upgrade K3s

About

This page shows you how to upgrade k3s on your cluster.

Steps

Take a backup of your cluster datastore

Below is with a sqlite datastore (For other datastore, see datastore backup)

Check the db files

du -sh /var/lib/rancher/k3s/server/db/*

The three files together form a single logical database:

state.db — the main database (maybe behind the WAL)
state.db-wal — committed transactions not yet checkpointed back into the main file
state.db-shm — shared memory index for the WAL (can be reconstructed, but include it anyway)
Stop k3s

systemctl stop k3s

Check that no running process uses the db, no output

lsof /var/lib/rancher/k3s/server/db/state.db

Checkpoint to integrate the wal in the db

sqlite3 state.db "PRAGMA wal_checkpoint(TRUNCATE);"
# only one file now
du -sh /var/lib/rancher/k3s/server/db/*

backup

cp /var/lib/rancher/k3s/server/db/state.db /var/lib/rancher/k3s/server/db/state.$(date +%Y%m%d_%H%M%S).db

restart

systemctl start k3s
systemctl status k3s

Choose the next minor version

Check the actual version

The one in:

In your cluster file

k3s_ansible:
  # https://github.com/k3s-io/k3s/releases
  version: 'v1.34.6+k3s1'
  token: '${KUBEE_INFRA_K3S_TOKEN}'

should be the same on the server

k3s --version

Version

Kubernetes versions are expressed as x.y.z, where

x is the major version,
y is the minor version,
and z is the patch version.

In Kubernetes versioning v1.32.2:

1 = major version
32 = minor version
2 = patch version

Don’t mess with the Skew Policy

K3s follows the Kubernetes version skew policy, which requires that you not skip intermediate minor versions when upgrading K3s. The policy for all Kubernetes distributions is to take single steps between minor versions - no skipping minors.

Skipping MINOR versions when upgrading is unsupported. Ensure that your plan does not skip intermediate minor versions when upgrading. https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/

The “don’t skip intermediate minor versions” rule means:

❌ Don’t go from 1.32.x → 1.34.x (skipping 1.33)
✅ Do go from 1.32.x → 1.33.x → 1.34.x (one minor version at a time)

Go check the next minor version

https://github.com/k3s-io/k3s/releases

Set the version in your cluster file

Example:

k3s_ansible:
  # https://github.com/k3s-io/k3s/releases
  version: 'v1.35.3+k3s1'
  token: '${KUBEE_INFRA_K3S_TOKEN}'

Execute the cluster upgrade

Execute the cluster upgrade with the default cluster chart

kubee --cluster clusterName cluster upgrade
# same as
# kubee --cluster clusterName --cluster-chart k3s-ansible cluster upgrade

Check the connection

kubee kubectl cluster-info

Support

Downgrade not supported, only rollback

k3s does not support any downgrade, but you can roll back

If you cannot restore the database, you cannot roll back to a previous minor version.

See k3s-backup