Upgrading k3s
Re-run the install script with a new version, or automate upgrades with the system-upgrade-controller.
Upgrading k3s replaces the binary and restarts the service. Your workloads and data stay put because they live in the datastore and on disk.
Manual upgrade
Re-run the install script pinned to the target version, or replace the binary and restart. Upgrade server nodes first, then agents.
Automated upgrade
For many nodes, install the system-upgrade-controller and describe the target version in a Plan resource. It drains, upgrades, and reboots nodes one at a time.
Example
# Manual upgrade to a specific version
curl -sfL https://get.k3s.io | \
INSTALL_K3S_VERSION=v1.30.6+k3s1 sh -
# Confirm the new version is running
kubectl get nodes
# VERSION column should now show v1.30.6+k3s1When to use it
- An operator upgrades a k3s cluster from v1.28 to v1.29 by re-running the install script with the new version environment variable on each node.
- A team uses the system-upgrade-controller to automatically apply k3s patch releases across all nodes during a maintenance window.
- A developer tests a k3s release candidate in a staging cluster by setting INSTALL_K3S_VERSION before promoting it to production nodes.
More examples
Upgrade k3s with the install script
Drains the node to evict pods, re-runs the installer with the target version, then restores scheduling.
# Drain the node first (on multi-node clusters):
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.29.4+k3s1 sh -
kubectl uncordon <node-name>Automated upgrade with SUC
Defines an upgrade Plan for the system-upgrade-controller to roll out the latest stable k3s release automatically.
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
name: k3s-server
namespace: system-upgrade
spec:
concurrency: 1
channel: https://update.k3s.io/v1-release/channels/stable
upgrade:
image: rancher/k3s-upgradeVerify the upgrade succeeded
Confirms the new k3s version is running on all nodes and checks for any pods that did not recover after the upgrade.
k3s --version
kubectl get nodes -o wide
kubectl get pods -A | grep -v Running | grep -v Completed
Discussion