K3S Upgrade: So aktualisieren Sie Ihren Cluster sicher und ohne Ausfallzeit

Kubernetes-Updates gehören zu den regelmäßigsten Wartungsaufgaben in jedem containerisierten Unternehmen. Während Standard-Kubernetes-Updates komplexe Prozeduren erfordern, die sorgfältig geplant und in maintenance windows durchgeführt werden, ist das Upgrade-Verfahren bei K3S erheblich einfacher. Dennoch gibt es einige Fallstricke, die den Unterschied zwischen einem reibungslosen Update und einem Ausfall mitten in der Produktion ausmachen können.

In dieser Anleitung behandeln wir alle relevanten Szenarien: das manuelle Upgrade eines Single-Node-Clusters, das schrittweise Upgrade eines Multi-Node-Clusters mit Server- und Agent-Nodes, die automatische Update-Funktion über den K3S-Update-Server und das kritische Thema der Zertifikatsrotation. Plus: wie Sie im Notfall einen Rollback durchführen, falls etwas schiefgeht.

Warum K3S-Updates so wichtig sind

Ein K3S-Cluster veraltet nicht nur optisch – mit der Zeit sammeln sich Sicherheitslücken in den verwendeten Basiskomponenten, Inkompatibilitäten mit neueren Helm-Charts und fehlende Unterstützung für aktuelle Kubernetes-Features an. Regelmäßige Updates sind daher keine Optionalität, sondern eine betriebliche Notwendigkeit.

K3S veröffentlicht regelmäßig neue Versionen, die sowohl Sicherheitspatches als auch Funktions-Updates enthalten. Die Release-Zyklen folgen den upstream Kubernetes-Releases mit einem typischen Abstand von wenigen Wochen. Aktuelle K3S-Versionen tragen das Format

, wobei X.Y.Z der Kubernetes-Versionsnummer entspricht.

Besonders kritisch sind die TLS-Zertifikate. K3S generiert bei der Installation Zertifikate, die standardmäßig 12 Monate gültig sind. Wenn diese Zertifikate ablaufen, ohne dass ein Upgrade durchgeführt wurde, wird der API Server keine Verbindungen mehr akzeptieren – der gesamte Cluster ist dann nicht mehr steuerbar. Dieses Szenario lässt sich durch regelmäßige Updates vollständig vermeiden.

Vorbereitung: Backup des Cluster-Zustands

Bevor ein Upgrade durchgeführt wird, sollte immer ein Snapshot des aktuellen Cluster-Zustands erstellt werden. K3S bringt einen eingebauten etcd-Snapshot-Mechanismus mit, der genau für diesen Zweck gedacht ist.

Manuellen Snapshot erstellen

1
2
3
4
5
6
7
8
9
10
11
# Kurz-Snapshot (Standard: /var/lib/rancher/k3s/server/db/snapshots/)

sudo k3s etcd-snapshot save



# Oder mit explizitem Namen und S3-Backup

sudo k3s etcd-snapshot save --name pre-upgrade-$(date +%Y%m%d) \

  --s3 \

  --s3-endpoint=https://s3.amazonaws.com \

  --s3-bucket=k3s-backups \

  --s3-folder=cluster-01 \

  --s3-access-key=IHRE_ACCESS_KEY \

  --s3-secret-key=IHRE_SECRET_KEY

Der Snapshot enthält den gesamten Cluster-Zustand: alle Deployments, Services, ConfigMaps, Secrets, RBAC-Regeln und Ingress-Konfigurationen. Ohne einen Snapshot gibt es keine zuverlässige Möglichkeit, den Cluster im Fehlerfall恢复到 einem bekannten Zustand zurückzuführen.

Die Sicherung auf S3 ist besonders für Produktivumgebungen empfehlenswert, da der Snapshot dann auch bei einem vollständigen Node-Ausfall verfügbar bleibt. In einer lokalen Umgebung genügt auch die Standardspeicherung auf dem Server selbst.

Snapshots auflisten

1
sudo k3s etcd-snapshot ls

Dieser Befehl zeigt alle verfügbaren Snapshots mit Namen, Zeitstempel und Speicherort an. Vergewissern Sie sich, dass der gerade erstellte Snapshot in der Liste erscheint, bevor Sie mit dem Upgrade fortfahren.

Manuelles Upgrade: Single-Node-Cluster

Das Upgrade eines Single-Node-K3S-Clusters ist denkbar einfach. Der Prozess besteht im Wesentlichen aus dem Austausch des K3S-Binärfiles und dem Neustart des Dienstes. Für einen Single-Node-Cluster, der als Entwicklungsumgebung oder für nicht-kritische Workloads dient, genügt dieses Vorgehen.

Schritt 1: Aktuelle Version ermitteln

1
2
kubectl get nodes

# Ausgabe zeigt die aktuelle K3S-Version, z. B. v1.31.1+k3s2

Oder direkt auf dem Server:

1
2
k3s --version

# Ausgabe: k3s version v1.31.1+k3s2 (commit 1234567)

Notieren Sie sich die aktuelle Version. Dies ist wichtig, falls ein Rollback erforderlich wird.

Schritt 2: Verfügbare Versionen prüfen

1
2
curl -s https://api.github.com/repos/k3s-io/k3s/releases/latest | grep tag_name

# Ausgabe: "tag_name": "v1.31.2+k3s1"

Alternativ können Sie die Release-Seite auf GitHub besuchen, um die aktuellen Versionen und die zugehörigen Changelogs einzusehen. Achten Sie besonders auf Release Notes, die bekannte Probleme oder Breaking Changes beschreiben.

Kubernetes-Upgrades sollten idealerweise versionsweise erfolgen – also nicht von v1.28 direkt auf v1.31 springen, sondern über v1.29 und v1.30 gehen. Innerhalb des K3S-Ökosystems ist dieses schrittweise Vorgehen zwar technisch nicht zwingend erforderlich, aber es reduziert das Risiko von Kompatibilitätsproblemen mit bestehenden Workloads erheblich.

Schritt 3: Upgrade durchführen

Das Upgrade erfolgt über dasselbe Installationsskript, das auch für die Erstinstallation verwendet wird – mit dem entscheidenden Unterschied, dass das bestehende Binärfile ersetzt und der Dienst neu gestartet wird:

1
curl -sfL https://get.k3s.io | sh -

Durch das Setzen der Umgebungsvariablen

können Sie steuern, auf welchem Kanal nach Updates gesucht wird:

1
2
3
4
5
# Stable-Kanal (empfohlen für Produktion)

curl -sfL https://get.k3s.io | K3S_CHANNEL=stable sh -



# Oder spezifische Version installieren

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.31.2+k3s1 sh -

Nach dem Upgrade startet K3S automatisch neu. Die kubeconfig bleibt unverändert – kubectl zeigt weiterhin auf den Cluster.

Schritt 4: Upgrade verifizieren

1
2
3
4
5
kubectl get nodes

# Die Version sollte die neu installierte Version anzeigen



k3s --version

# Bestätigt die neue Version auf dem Server

Prüfen Sie anschließend, ob alle Workloads noch laufen:

1
2
kubectl get pods -A | grep -v Running

# Wenn keine Ausgabe: alle Pods laufen正常

Bei einem Single-Node-Cluster kann es während des Neustarts zu einer kurzen Unterbrechung kommen – typischerweise sind die Kontrollebenen-Komponenten für etwa 30 bis 60 Sekunden nicht erreichbar. Falls Pods mit einer Restart-Policy von „Always“ konfiguriert sind, werden diese automatisch neu gestartet, sobald der API Server wieder verfügbar ist.

Manuelles Upgrade: Multi-Node-Cluster

Ein Multi-Node-Cluster erfordert eine sorgfältigere Upgrade-Strategie als ein Single-Node-Setup. Die Grundregel lautet: zuerst die Server-Nodes, dann die Agent-Nodes – und niemals alle Server gleichzeitig upgraden.

Diese Reihenfolge ist entscheidend, weil der eingebettete etcd-Cluster eine konsistente Mehrheit benötigt, um den Cluster-Zustand aufrechtzuerhalten. Wenn mehr als die Hälfte der Server-Nodes gleichzeitig upgedatet werden, kann etcd seine Majority verlieren – der Cluster wird dann schreibgeschützt oder fällt vollständig aus.

Upgrade-Strategie: Rolling Upgrade

Für einen K3S-Cluster mit drei Server-Nodes und mehreren Agent-Nodes sieht das schrittweise Upgrade folgendermaßen aus:

• Phase 1: Erster Server-Node upgraden. Der Cluster verliert keine Majority, da zwei von drei Servern weiterlaufen.
• Phase 2: Zweiter Server-Node upgraden. Nun laufen alle Server auf der neuen Version.
• Phase 3: Dritter Server-Node upgraden (falls vorhanden).
• Phase 4: Agent-Nodes upgraden – jeweils einzelne Nodes, mit Pause dazwischen.

Zwischen den einzelnen Upgrade-Schritten sollte jeweils eine kurze Pause eingelegt werden, um den Cluster-Status zu prüfen und sicherzustellen, dass alle Nodes den Status „Ready“ haben, bevor der nächste Schritt erfolgt.

Server upgraden

Auf jedem Server-Node führen Sie dasselbe Upgrade-Kommando aus wie beim Single-Node:

1
curl -sfL https://get.k3s.io | K3S_VERSION=v1.31.2+k3s1 sh -

Nach dem Upgrade des ersten Servers prüfen Sie den Cluster-Status:

1
2
kubectl get nodes -o wide

# Alle Server-Nodes sollten "Ready" sein

Warten Sie, bis alle Server-Nodes den Status „Ready“ erreicht haben, bevor Sie den nächsten Server upgraden. Dies kann je nach Cluster-Größe und laufenden Workloads einige Minuten dauern.

Agent-Nodes upgraden

Agent-Nodes werden upgegradet, indem das K3S-Agent-Binärfile ausgetauscht wird. Der entscheidende Unterschied zum Server-Upgrade: Agent-Nodes können deutlich toleranter gegenüber gleichzeitigen Upgrades sein, da Kubernetes die laufenden Pods automatisch auf andere Nodes umplant, wenn ein Agent vorübergehend nicht verfügbar ist.

Vorausgesetzt, Ihr Cluster verfügt über ausreichend Kapazität auf den verbleibenden Agent-Nodes:

1
2
3
4
5
# Auf dem Agent-Node:

curl -sfL https://get.k3s.io | K3S_URL=https://<server-ip>:6443 \

  K3S_TOKEN=<node-token> \

  K3S_VERSION=v1.31.2+k3s1 \

  sh - agent

Um die Auswirkungen auf laufende Workloads zu minimieren, empfiehlt es sich, die Agent-Nodes nacheinander zu upgraden – mit einer kurzen Prüfpause zwischen jedem Upgrade. So können Sie sicherstellen, dass keine Pods aufgrund von Ressourcenengpässen im Status „Pending“ hängen bleiben.

Cluster-Status nach dem Upgrade prüfen

1
2
3
4
5
kubectl get nodes

# Alle Nodes sollten Ready sein – Version sollte die neue sein



kubectl get pods -A --field-selector=status.phase!=Running

# Leer? Alle Pods laufen wie erwartet

Falls Pods nach dem Upgrade im Status „Pending“ hängen, prüfen Sie die Events des betroffenen Pods:

1
kubectl describe pod <pod-name> -n <namespace> | grep -A 20 Events

Typische Ursachen sind: unzureichende Ressourcen nach dem Node-Upgrade, geänderte Pod Security Policies oder aktualisierte Images, die nicht mehr gefunden werden können.

Automatisches Upgrade mit dem K3S Update Server

Für Produktivumgebungen, die regelmäßige Updates erfordern, bietet K3S einen eingebauten Update-Mechanismus über den sogenannten K3S Update Server. Dieser automatisiert das Upgrade-Prozess und ermöglicht kontrollierte, versionierte Rollouts über den gesamten Cluster.

Update Server einrichten

Der K3S Update Server kann als Kubernetes-Deployment innerhalb des Clusters oder als separater Server betrieben werden. Für die meisten Umgebungen genügt ein Deployment innerhalb des Clusters:

1
2
# Update Server deployen (Release-Channel: stable, v1.31.2)

kubectl apply -f https://github.com/k3s-io/k3s-upgrade/releases/latest/download/k3s-upgrade-manifest.yaml

Dieses Manifest erstellt einen Deployment mit dem K3S Update Controller und konfiguriert die notwendigen RBAC-Regeln und Webhooks.

Automatisches Upgrade aktivieren

Um das automatische Upgrade zu aktivieren, setzen Sie auf jedem Node die Umgebungsvariable

und optional :

1
2
3
4
5
6
7
# In /etc/systemd/system/k3s.service.env oder beim Start:

K3S_UPDATE_SERVER=https://update-server.internal

K3S_UPDATE_CHANNEL=https://update-server.internal/channel/v1.31.2+k3s1



# Oder direkt beim Installation:

curl -sfL https://get.k3s.io | K3S_UPDATE_SERVER=https://update-server.internal \

  K3S_UPDATE_CHANNEL=stable sh -

Der Update-Server prüft regelmäßig (standardmäßig alle 24 Stunden), ob eine neuere Version verfügbar ist. Falls ja, initiiert er ein Upgrade des jeweiligen Nodes. Sie können den Prozess jedoch so konfigurieren, dass Updates nur zu bestimmten Zeiten durchgeführt werden – etwa außerhalb der Geschäftszeiten.

Zertifikatsrotation: Das Critical-Update-Szenario

Ein Thema, das bei K3S-Updates häufig übersehen wird: die TLS-Zertifikate. K3S generiert bei der Installation Zertifikate für den API Server, den etcd-Cluster und die kubelet-Kommunikation. Diese Zertifikate sind standardmäßig 12 Monate gültig.

Wenn diese Zertifikate ablaufen, ohne dass ein Upgrade oder eine Rotation durchgeführt wurde, wird der Cluster nicht mehr funktionsfähig. Der API Server lehnt alle Verbindungen ab, kubectl meldet „Unable to connect to the server: x509: certificate has expired or is not yet valid“.

Zertifikatsstatus prüfen

1
2
sudo k3s certificate rotate --help

# Zeigt alle verfügbaren Zertifikate

Um den Ablaufzeitpunkt der Zertifikate zu prüfen:

1
sudo openssl x509 -in /var/lib/rancher/k3s/server/tls/service.key -noout -dates

Alternativ: Ein Upgrade auf die neueste K3S-Version aktualisiert die Zertifikate automatisch auf einen neuen 12-Monats-Zyklus. Der sicherste Weg, Zertifikatsprobleme zu vermeiden, ist daher ein regelmäßiges Upgrade – etwa vierteljährlich.

Manuelle Zertifikatsrotation

Falls Sie die Zertifikate manuell rotieren möchten, ohne ein vollständiges Upgrade durchzuführen:

1
2
3
4
5
# Zertifikate rotieren (Cluster muss im Wartungsmodus sein)

sudo k3s certificate rotate



# Danach K3S neu starten

sudo systemctl restart k3s

Beachten Sie, dass die Zertifikatsrotation den API Server kurzzeitig unavailable macht. Planen Sie diesen Schritt entsprechend als maintenance window.

Rollback: So kehren Sie zur vorherigen Version zurück

Falls ein Upgrade schiefgeht – etwa weil ein Helm-Chart nach dem Update nicht mehr kompatibel ist oder ein Workload unerwartete Fehler zeigt – können Sie den Cluster auf verschiedene Weise恢复到 einen bekannten Zustand zurückführen.

Schnell-Rollback über das vorherige Binärfile

Das K3S-Installationsskript sichert das vorherige Binärfile automatisch unter

. Dieses kann ohne Deinstallation wiederhergestellt werden:

1
2
3
4
# Auf dem betroffenen Node:

sudo cp /var/lib/rancher/k3s/server/bin/k3s.backup /usr/local/bin/k3s

sudo chmod +x /usr/local/bin/k3s

sudo systemctl restart k3s

Dieses Verfahren funktioniert besonders bei Server-Nodes in Multi-Node-Clustern, da das Backup-Binärfile auf jedem Node separat gespeichert wird.

Best Practices für K3S-Updates

Praxis	Beschreibung
Regelmäßige Upgrades	Mindestens alle 3 Monate upgraden – idealerweise monatlich. Das reduziert die Anzahl der zu überspringenden Versionen.
Immer Snapshot vorher	Vor jedem Upgrade einen etcd-Snapshot erstellen. Auch wenn das Upgrade erfolgreich ist – der Snapshot schützt vor Fehlern der nächsten Maintenance.
Staging-Umgebung	Upgrades zuerst in einer Staging-Umgebung testen, bevor sie auf Produktion angewendet werden.
Server zuerst, Agents danach	In Multi-Node-Clustern immer erst die Server upgraden, dann die Agent-Nodes.
Nie alle Server gleichzeitig	Zwischen den Server-Upgrades warten, bis alle Server den Status „Ready“ erreicht haben.
Monitoring beobachten	Nach jedem Upgrade die Pod-Logs, API-Server-Logs und die Node-Status für mindestens 15 Minuten beobachten.
Helm-Charts kompatibel halten	Prüfen Sie vor dem Upgrade, ob alle installierten Helm-Charts mit der neuen Kubernetes-Version kompatibel sind.

Sie möchten K3S sicher in Ihrem Unternehmen betreiben?

Wir unterstützen Sie bei der Einrichtung, Wartung und beim Upgrade Ihrer K3S-Infrastruktur – ob als Einzellösung oder als Basis für Ihre containerisierte KI-Infrastruktur. Kontaktieren Sie uns über unser Kontaktformular – wir melden uns innerhalb von 24 Stunden bei Ihnen.