Zum Inhalt springen
Deutsch

Upgrade-Strategien

Zwei Arten von Produktions-Upgrade:

ArtMuster
Code-only-UpgradeNeue 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 UpgradeNeue 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.

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.

UpgradeMixed-Version-FensterWie das Scheitern aussieht
v0.15.x → v0.16.0Nicht 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.0Nicht 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.0Nicht 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.

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.

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.

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.

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 currency auf 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.

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.

// 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:

  1. Das neue Feld als optional im Message-Typ ergänzen.
  2. Neuer Code kann Nachrichten ohne das Feld handhaben (es defaulten).
  3. 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.

# v1 → v2: umbenannter Config-Key
actor-ts.cluster.gossip-interval = 1s # v1
actor-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.conf zu 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.

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.

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.