Upgrade-Strategien
Zwei Arten von Produktions-Upgrade:
| Art | Muster |
|---|---|
| Code-only-Upgrade | Neue Binary, gleiche Schemas. Rolling Deployment — alte + neue Versionen koexistieren kurz, außer über ein Release hinweg, das den Cluster-Wire ändert (siehe unten). |
| Schema-brechendes Upgrade | Neue Shapes für Events / State / Messages. Erst Migration, dann Rolling Deployment. |
Wähle die Art, folge dem Muster. Naiv zu mischen bricht Produktion — alte Nodes können neue Schemas nicht lesen oder umgekehrt.
Cluster-Wire-Kompatibilität pro Release
Abschnitt betitelt „Cluster-Wire-Kompatibilität pro Release“Ein Rolling Deployment setzt voraus, dass das Mixed-Version-Fenster überlebbar ist — für ein paar Minuten reden alte und neue Nodes miteinander. Diese Annahme ist eine Eigenschaft des Releases, nicht deines Codes, und zwei aufeinanderfolgende Releases brechen sie. Keiner der beiden Brüche ist eine Schema-Änderung in dem Sinn, in dem diese Seite das Wort benutzt — Events, State und Konfiguration bleiben unangetastet —, also greift auch keines der additiven Muster weiter unten.
| Upgrade | Mixed-Version-Fenster | Wie das Scheitern aussieht |
|---|---|---|
| v0.15.x → v0.16.0 | Nicht sicher (#112) | Jeder Gossip-Frame trägt eine sequence, und GossipMessage bekommt ein Pflichtfeld. Ein aktualisierter Peer weist die Frames eines alten Nodes zurück; ein alter Node ignoriert die eines aktualisierten. Nichts wirft einen Fehler — die Membership konvergiert still nie, solange beide Versionen laufen, der Cluster einigt sich also nie darauf, wer dazugehört. |
| v0.16.0 → v0.17.0 | Nicht sicher (#450) | Frames sind ein getaggter JSON-Baum statt blanker JSON.stringify-Ausgabe. Der meiste Alt-Verkehr dekodiert unverändert; ein Legacy-Body, der bereits die Gestalt eines reservierten Tags hatte, nicht. __map__, __set__, __regexp__, __bigint__, __url__, __number__ und __error__ werfen in beliebiger Tiefe, und ein Decoder-Throw kostet die ganze Verbindung mitsamt jedem Frame, der in denselben Chunk gebatcht wurde. Zwei scheitern stattdessen still: __bytes__ dekodiert zu einem Uint8Array, __date__ zu einer Invalid Date. Die Gegenrichtung ist schlicht verlustbehaftet — ein älterer Node liest den Tag-Wrapper als gewöhnliche Daten. |
| v0.17.x → v0.18.0 | Nicht sicher (#823) | Das Cluster-Wire erhält eine Version, die jeder Handshake ankündigt, und Version 2 verlangt, dass jede Node-Adresse auf einem Frame ihre Inkarnation nennt. Anders als die beiden Zeilen darüber scheitert diese laut: Ein v0.18.0-Node weist das hello eines älteren Nodes mit einem hello-refused ab und schreibt auf seiner Seite eine WARN mit beiden Versionen, und ein älterer Node loggt diesen Frame als nicht zugeordnet, mit dem Grund darin. Die beiden bilden nie einen Cluster. |
Aktualisiere den Cluster in einem Schritt. Alle Nodes stoppen, dann alle Nodes auf der neuen Version starten. Keine Zwischenversion macht eine dieser Etappen rollbar, ein Sprung über mehrere davon braucht also dieselbe Behandlung — einmal statt einmal pro Etappe.
Ab v0.18.0 sagt es der Handshake. Jedes hello und hello-ack trägt die
Cluster-Wire-Versionen, die der Node spricht
(#823), und zwei Nodes
ohne gemeinsame Version weisen einander beim Handshake ab — ein
hello-refused mit dem Grund und eine WARN auf beiden Seiten —, statt halb zu
funktionieren. Ein künftiges Release, das das Wire ändert, kann dann einen
Bereich von Versionen sprechen und ein Rolling Upgrade möglich halten; eines,
das das Minimum anhebt, ist wieder ein Upgrade mit Stopp und Start, und diese
Tabelle sagt, welches.
Code-only-Upgrades
Abschnitt betitelt „Code-only-Upgrades“Der häufige Fall. Bugfixes, Refactorings, Verhaltens-Tweaks ohne Änderung der persistierten Datenformen.
1. Die neue Binary bauen (Tag v1.2.3).2. Per Rolling Update deployen.3. K8s ersetzt Pods einen nach dem anderen.4. Jeder Pod: SIGTERM → Coordinated Shutdown → Drain → neuer Pod spawnt → Cluster-Rejoin.5. Fertig.Gossip + Sharding-Rebalance + Coordinated Shutdown des Clusters übernehmen die Choreographie. Gesamt-Downtime: null (bei richtiger Konfiguration; siehe Kubernetes-Deployment).
Voraussetzungen:
- Replicas ≥ 2. Ein-Replica-Cluster können nicht sauber drainen.
- Coordinated Shutdown mit vernünftigen Phasen-Timeouts konfiguriert.
- Health-Checks gaten Readiness korrekt.
Den Rollout am Cluster ablesen
Abschnitt betitelt „Den Rollout am Cluster ablesen“Ein Rolling Update ist ein Fenster, in dem zwei Releases deiner Anwendung in einem Cluster laufen, und die Frage, die sich ein Betreiber dabei immer wieder stellt, ist, welcher Node welches fährt. Lass jeden Node sein Release nennen:
actor-ts.cluster.app-version = ${?APP_VERSION}Setze APP_VERSION im Deployment neben dem Image-Tag, und jedes Mitglied
trägt das Label im Gossip.
GET /cluster/members
listet es dann pro Mitglied, und jede Logzeile, die ein Mitglied ausgibt,
zeigt es als app-version=… — ein hängender Rollout lässt sich so als Zahl
der Mitglieder lesen, die noch auf dem alten Release sind, statt als
Vermutung. Das Label ist rein informativ: nichts platziert, routet oder downt
danach, und ein Node, der keines nennt, erscheint einfach ohne.
Ein Wert aus der Umgebung wird zuerst als JSON gelesen, wo immer er sich als
JSON parsen lässt. Eine Version, die sich wie eine Zahl liest, kommt in der
Schreibweise dieser Zahl zurück — 1.10 als 1.1, 2.0 als 2, 1e3 als
1000 —, die Releases 1.1 und 1.10 tragen also dasselbe Label, eine ganze
Zahl jenseits von Number.MAX_SAFE_INTEGER kann mit anderen letzten Ziffern
zurückkommen (20261104123456789 als 20261104123456788), und eine, die sich
wie null, eine Liste oder ein Objekt liest, lässt den Start mit einem
ConfigError scheitern; eine Version mit einem zweiten Punkt (1.2.3) oder
einem Buchstaben (v1.10) bleibt unverändert. Einen solchen Wert in der Variablen selbst quoten
(APP_VERSION='"1.10"') oder im Code mit withAppVersion(...) setzen.
Das Label gehört zu dem Lauf, der es nennt. Ein Node, der ohne Label neu
startet — zurückgerollt auf ein Release, das keines setzt, oder ohne
APP_VERSION deployt —, erscheint ohne, nie mit dem Label des Laufs davor:
Ein Peer, der vom Neustart noch nichts gehört hat, gossipt weiter den Eintrag
des vorigen Laufs, und dieser Eintrag zählt für die Adresse nicht mehr.
Das erste Upgrade auf ein actor-ts-Release, das das Feld kennt, ist selbst schon ein Rollout, den das Label abdeckt. Ein Node, der noch auf dem älteren actor-ts läuft, lässt das Label aus jedem Eintrag fallen, den er weitergibt; für einen Moment kann ein Peer ein Mitglied also ohne Label zeigen — und der eigene Gossip des Mitglieds setzt es innerhalb weniger Runden wieder.
Schema-brechende Upgrades
Abschnitt betitelt „Schema-brechende Upgrades“Immer wenn das Upgrade ändert:
- Event-Shapes in einem Journal.
- State-Shapes in einem Durable-State-Store.
- Message-Shapes, die Nodes einander während des Rolling-Fensters schicken könnten.
- Config-Keys, die sich zwischen Major-Versionen bewegen.
Das Muster: Mach die Änderung additiv, dann upgrade.
Muster — additive Event-Shapes
Abschnitt betitelt „Muster — additive Event-Shapes“Alter Code schrieb:
type DepositedV1 = { kind: 'deposited'; amount: number };Neuer Code will:
type DepositedV2 = { kind: 'deposited'; amount: number; currency: string };Schritt 1: Zwischen-Code deployen, der beide Shapes akzeptiert.
class Account extends PersistentActor<...> { override eventAdapter() { return defaultsAdapter<DepositedV2>({ manifest: 'Deposited', currentVersion: 2, defaults: { 1: { currency: 'USD' } }, }); }}Dieser Schritt:
- Schreibt V2-Events unter der neuen Form.
- Liest V1-Events mit
currencyauf USD defaulted. - Funktioniert in alten + neuen Clustern, weil alter Code seine eigene Form liest und Envelope-Wrapping ignoriert.
Roll das über Standard-Rolling-Deployment aus.
Schritt 2 (optional später) — den defaultsAdapter droppen,
sobald alle alten Events ausgealtert oder snapshottet sind. Meist
unbegrenzt zur Sicherheit behalten.
Siehe Migration Recipes für den Per-Muster-Walkthrough.
Muster — nicht-additive Schema-Änderungen
Abschnitt betitelt „Muster — nicht-additive Schema-Änderungen“Für Renames, Restructures, entfernte Felder brauchen die Mechaniken mehr Schritte:
1. Code deployen, der ALTES LIEST + NEUES SCHREIBT. (`migratingAdapter`)2. Vollständig ausrollen. Alle neuen Events sind jetzt in der neuen Form.3. Code deployen, der NUR NEUES LIEST (unterstützt Altes nicht mehr). Droppt den Migrating-Schritt.4. Optional: Bulk-Migration, um noch existierende alte Events in die neue Form umzuschreiben, wenn du Adapter-Komplexität droppen willst.Siehe migratingAdapter für die Implementierung.
Inter-Actor-Message-Änderungen
Abschnitt betitelt „Inter-Actor-Message-Änderungen“// v1-Nachricht: { kind: 'request' }// v2-Nachricht: { kind: 'request', traceId: string }Während eines Rolling Deployments könnten alte Nodes v1 an neue Nodes senden (oder umgekehrt). Der neue Code muss beide Versionen eingehender Nachrichten tolerieren.
Strategie:
- Das neue Feld als optional im Message-Typ ergänzen.
- Neuer Code kann Nachrichten ohne das Feld handhaben (es defaulten).
- Deployen. Alt → neu sendet ohne das Feld, funktioniert. Neu → alt sendet mit dem Feld, alt ignoriert es.
Sobald alles auf v2 ist, kann das Feld in einem späteren Deployment required werden.
Konfigurationsänderungen
Abschnitt betitelt „Konfigurationsänderungen“# v1 → v2: umbenannter Config-Keyactor-ts.cluster.gossip-interval = 1s # v1actor-ts.cluster.gossip-interval-ms = 1000 # v2 (umbenannt)Das Config-System des Frameworks migriert umbenannte Keys nicht automatisch. Zwei Strategien:
- Beide lesen im Code, der Config lädt; entweder den Namen ehren, bis du den neuen verlangen kannst.
- Migrations-Skripte laufen lassen, die
application.confzu den neuen Key-Namen umschreiben.
Einfacher: Config-Keys nicht umbenennen. Wenn doch nötig, alten Namen deprecaten + beim Start für ein Release warnen, bevor er entfernt wird.
Was, wenn du Downtime nicht vermeiden kannst?
Abschnitt betitelt „Was, wenn du Downtime nicht vermeiden kannst?“Manchmal ist der Schema-Break so schlimm, dass eine Online-Migration ehrlich gesagt unmöglich ist — anderes Storage-Backend, fundamentales Restructuring. Dann plane Downtime:
1. Wartungsfenster ankündigen.2. Coordinated Shutdown des gesamten Clusters.3. Offline-Migrations-Skripte laufen lassen (manchmal Stunden).4. Die neue Version hochfahren.5. Smoke-Test vor User-Traffic.Frequenz: idealerweise nie. Aber gelegentlich unvermeidlich.
Rollback-Strategie
Abschnitt betitelt „Rollback-Strategie“Hab immer einen Rollback-Plan:
- Code-only: Vorherige Binary funktioniert weiter gegen dieselben Schemas. Rollback per K8s-Rolling-Back.
- Schema-brechend: Der vorherige Code liest die neuen Shapes (weil Schritt 1 additiv war). Rollback ist sicher.
- Nicht-additive Änderung: schwieriger — der Rollback-Schritt muss auch die neue Form kennen. Vermeiden; wenn nötig, Feature-Flags nutzen, um den neuen Code-Pfad zu gaten, während der alte erreichbar bleibt.
Wohin als nächstes
Abschnitt betitelt „Wohin als nächstes“- Operations-Überblick — die Produktions-Checkliste.
- Rolling Migration — das praktische Schritt-für-Schritt-Rezept.
- Migration-Überblick — Schema-Evolution für Events + State.
- Migration Recipes — das Kochbuch.
- Coordinated Shutdown — die Graceful-Stop-Maschinerie, auf die Rolling Deploys angewiesen sind.
