Einen Cluster upgraden

Ein Upgrade bringt einen Cluster auf ein neueres Release: ein getestetes, signiertes Paket aus dem Node-Image mit seinem k3s, pbx-agent und den Add-ons. Diese Seite startet eines, sofort oder im Wartungsfenster des Clusters, setzt das Fenster und den Kanal, und sagt, was passiert, wenn ein Upgrade fehlschlägt.

In Arbeit: noch nicht buchbar

Gebaut im Labor: Am 2026-10-10 hat pbx-agent einen Cluster auf einem echten Hetzner-Server in 83 Sekunden von Release 2026.10.0 auf 2026.10.1 gebracht, mit einem Snapshot vorher; der Node startete neu, und dabei war die API 34 Sekunden lang nicht erreichbar. Die automatische Rückkehr zum vorigen Image nach einem ungesunden Start und die Upgrades und Neustarts, die auf das Wartungsfenster warten, sind In Arbeit: gebaut und gegen simulierte Gegenstellen getestet, auf einem echten Node noch nicht gelaufen. Die Oberfläche des Portals ist englisch, darum stehen ihre Beschriftungen hier auf Englisch. Sag mir, wenn es buchbar ist.

Auf einem einzelnen Node startet jedes Upgrade den Server neu. Die Kubernetes-API und deine Apps sind weg, solange er neu startet, bis ihre Pods wieder laufen. Wähle den Zeitpunkt, oder lass das Fenster ihn wählen.

Was du brauchst

• Du bist Team-Admin. Mitglieder sehen die Seite, können aber kein Upgrade starten.
• Einen Cluster im Zustand bereit, ohne ein anderes Upgrade in der Warteschlange oder in Arbeit.
• Ein Release, das ihm angeboten wird. Gibt es keines, sagt die Seite Upgrades „No newer release is offered for this cluster on its channel”.

Ein Upgrade starten

1. Öffne auf der Seite des Clusters Upgrades. Sie zeigt das Release, das der Cluster fährt, und das nächste Release, das sein Kanal anbietet, mit seinen Notizen und einer Plakette: patch: same k3s minor oder new k3s minor.

2. Wähle, wann:

   • In the next window, mit dem Beginn des Fensters daneben, oder
   • Now: pbx-agent nimmt es beim nächsten Abgleich, etwa 30 Sekunden später.

3. Verfolge es. Die Seite zeigt das Upgrade erst als eingereiht, dann jeden Schritt, wie pbx-agent ihn meldet; Operations hat das ganze Protokoll. Ist es fertig, zeigt die Seite das neue Release, und Upgrade history behält den Lauf.

4. Prüf deine Apps.

Einem Cluster wird nur ein Release angeboten, das sein aktuelles unter den Releases nennt, von denen aus es getestet wurde. Ein Upgrade für das Fenster, das sein Fenster verpasst, weil pbx-agent nicht rechtzeitig erreichbar war, rückt ins nächste Fenster; nach 14 Tagen verfällt es.

Was bei einem Upgrade passiert

k3s ist Teil des Node-Images, und das Root-Dateisystem des Images ist schreibgeschützt. Ein Upgrade von k3s, vom Betriebssystem oder von beidem ist darum dasselbe: Das ganze Image wird ersetzt, an Ort und Stelle, auf demselben Server. Der Server wird nicht neu aufgebaut, und die Daten auf seiner Platte bleiben.

1. Vorprüfung: Der Node ist gesund, hat Platz auf der Platte, und die Signatur des Releases stimmt.
2. Snapshot: pbx-agent macht den Snapshot pbx-pre-upgrade-<release> und bestätigt, dass er in deinem Bucket angekommen ist.
3. Laden: Er lädt das neue Image und prüft es gegen das signierte Release.
4. Bereitlegen: Er schreibt das neue Image neben das laufende, als zweiten Booteintrag.
5. Neustart: Er startet einmal in das neue Image.
6. Gesundheitsprüfung: Er wartet auf die Kubernetes-API, darauf, dass der Node mit dem neuen k3s Ready ist und den neuen Eintrag fährt, und darauf, dass jedes Deployment in kube-system verfügbar ist.
7. Festschreiben: Das neue Image wird zum Standard. Der Node behält zwei Einträge: den neuen und den, von dem er kam.

Im Laborlauf vom 2026-10-10 dauerten diese Schritte 83 Sekunden vom Einplanen bis zum Erfolg, Garden Linux 2150.6.0 auf 2150.11.0, und die API war 34 Sekunden lang nicht erreichbar, während der Node neu startete. Davor, am 2026-09-24, hat der eigene Test des Images in einer virtuellen Maschine 24 von 24 Prüfungen für ein Update an Ort und Stelle und die Rückkehr zum vorigen Image bestanden: Die Volumes auf der Platte des Nodes behielten ihre Identität, und eine Postgres-Tabelle und eine Datei lasen sich nach beidem unverändert zurück.

Wenn ein Upgrade fehlschlägt

• Ist der Node 20 Minuten nach dem Neustart nicht gesund, startet pbx-agent ihn in das vorige Image neu, und das Upgrade gilt als fehlgeschlagen.
• Kommt der Node im neuen Image mit der falschen k3s-Version hoch, wartet pbx-agent nicht: Er startet ihn sofort in das vorige Image neu, und das Upgrade schlägt fehl.
• Kommt der Node im vorigen Image hoch, hat das neue nicht gebootet; das Upgrade schlägt sofort fehl, ohne Neustart.
• In Arbeit Diese Rückkehr in das vorige Image ist auf einem echten Node noch nicht ausgelöst worden.
• Schlägt nur das Festschreiben fehl, fährt der Node das neue Image, sein nächster Neustart würde aber das alte starten. Die Meldung des Upgrades sagt das.

In Arbeit Die Admins des Teams bekommen eine Mail über ein fehlgeschlagenes Upgrade. Der Snapshot aus Schritt 2 bleibt in deinem Bucket; ein fehlgeschlagenes Upgrade allein braucht keine Wiederherstellung. Fehlerbehebung hat die Einzelheiten.

Das Wartungsfenster

Wähle auf Settings des Clusters unter Maintenance window die Tage (Days), Beginn (From), Ende (To) und die Zeitzone (Time zone), dann Save. Voreingestellt sind Samstag und Sonntag, 02:00 bis 05:00 Uhr, Europe/Berlin. Die Tage sind die Tage, an denen ein Fenster beginnt; ein Ende vor oder gleich dem Beginn läuft über Mitternacht. Das Fenster behält seine Uhrzeiten über die Zeitumstellung hinweg, in diesen Nächten kann es also eine Stunde kürzer oder länger sein.

In Arbeit Drei Dinge warten auf das Fenster:

• ein Upgrade, das du In the next window eingeplant hast,
• ein Patch-Release, das ohne Klick kommt (unten),
• ein Neustart von k3s, den eine geänderte Einstellung braucht, etwa ein neuer Snapshot-Zeitplan. pbx-agent schreibt die Änderung sofort und startet k3s im nächsten Moment innerhalb des Fensters neu, nie während eine Operation läuft.

Kanal und Patch-Releases

Wähle unter Upgrades → Channel den Kanal (Release channel) und, ob Patch-Releases ohne Klick im Fenster kommen (Install patch releases in the window without a click), dann Save. Das Portal prüft das Release des Kanals jede Stunde.

• early bekommt ein neues Release zuerst; stable bekommt es, nachdem es auf early gelaufen ist. Bevor ein Release early erreicht, läuft es in einem Labor bei Hetzner und dann drei Tage auf meinen eigenen Clustern; auf early bleibt es sieben Tage, bevor es stable erreicht (Releases und Kanäle).
• Ein Patch-Release behält die k3s-Minor-Version des Clusters. Mit gesetztem Haken (voreingestellt) wird es von selbst für das nächste Fenster eingereiht; ohne Haken wartet jedes Release auf deinen Klick.
• Eine neue k3s-Minor-Version wartet immer auf deinen Klick.

6 · Im Wartungsfenster upgradenDer Lernschritt: erst Staging, dann Produktion in ihrem Fenster.

Releases und KanäleWas ein Release enthält, wie es signiert und befördert wird, und welche Releases es gibt.