Cluster-Bootstrap
Ein Kaltstart stellt jedem Node im selben Moment dieselbe Frage —
„gibt es schon einen Cluster?” — und Discovery beantwortet sie auf
jedem anders. DNS ist noch nicht propagiert; ein Pod ist Ready,
bevor seine IP im Headless Service steht; die Kubernetes-API liefert
eine unvollständige Pod-Liste. Wer auf die erste Antwort hin handelt,
bekommt Nodes, die je einen Cluster aus der Teilmenge bilden, die sie
zufällig gesehen haben.
Gossip repariert das nie. Das Ergebnis sind getrennte Cluster mit demselben Namen — jeder mit eigenem Leader, eigenen Singletons und eigener Shard-Verteilung.
Cluster-Bootstrap ist die Phase, die vor Cluster.join läuft und
dafür sorgt, dass aus einem gleichzeitigen Start höchstens ein Cluster
entsteht.
Die zwei Regeln
Abschnitt betitelt „Die zwei Regeln“1 — Stable Observation. Den Seed-Provider im Takt von
pollIntervalMs pollen und verlangen, dass die zurückgegebene Menge
(plus dieser Node) für stableMarginMs exakt identisch bleibt, bevor
darauf gehandelt wird. Jede Änderung startet die Margin neu. Ein
fehlgeschlagener Lookup ist keine leere Menge — er zählt gar nicht als
Beobachtung, damit ein DNS-Ausfall nie mit „ich bin allein” verwechselt
werden kann.
2 — Verzögerte Selbstwahl. Die stabile Menge nach Adresse sortieren.
Die niedrigste ist der Initial Seed — aber sie bildet nicht sofort
einen Cluster. Jeder Node, auch der Gewinner, joint mit den übrigen
Contact Points als Seeds; nur der Gewinner bekommt zusätzlich eine Frist
(selfElectionGraceMs), nach der er einen Cluster bildet, falls ihn bis
dahin niemand befördert hat.
Einschalten
Abschnitt betitelt „Einschalten“Der Einzeiler — bootstrapCluster führt die Phase für dich aus:
import { bootstrapCluster, ClusterBootstrapOptions } from 'actor-ts/cluster';
const bootstrapOptions = ClusterBootstrapOptions.create('my-app') .withHost(process.env.POD_IP!) .withPort(2552) .withDiscovery('kubernetes') .withStableObservation(true);const { cluster, shutdown } = await bootstrapCluster(bootstrapOptions);Statt true ein Objekt übergeben, um die Zeiten zu überschreiben:
const bootstrapOptions = ClusterBootstrapOptions.create('my-app') .withHost(process.env.POD_IP!) .withDiscovery('kubernetes') .withStableObservation({ requiredContactPoints: 3, stableMarginMs: 8_000 });Selbst steuern
Abschnitt betitelt „Selbst steuern“Wer Cluster.join direkt aufruft, führt die Beobachtung aus und gibt
beide Ergebnisse in die Optionen — die Seed-Liste und die
selfElection-Policy:
import { Cluster, ClusterOptions, NodeAddress, StableObservation, StableObservationOptions,} from 'actor-ts/cluster';
const selfAddress = new NodeAddress('my-app', process.env.POD_IP!, 2552);
const observationOptions = StableObservationOptions.create() .withSeedProvider(seedProvider) .withSelfAddress(selfAddress) .withRequiredContactPoints(3);const observation = new StableObservation(observationOptions);const targets = await observation.resolveJoinTargets();
const clusterOptions = ClusterOptions.create() .withHost(selfAddress.host) .withPort(selfAddress.port) .withSeeds(targets.seeds.map((address) => address.toString())) .withSelfElection(targets.selfElection);const cluster = await Cluster.join(system, clusterOptions);resolveJoinTargets() liefert die stabile Menge, ob dieser Node
gewonnen hat (isInitialSeed) und den selfElection-Wert zum
Weiterreichen. Diesen Wert selbst herzuleiten ist der eine Fehler, der
das Split-Brain zurückbringt — deshalb macht die Beobachtung es für dich.
Einstellungen
Abschnitt betitelt „Einstellungen“| Einstellung | Default | Bedeutung |
|---|---|---|
stableMarginMs | 5000 | Wie lange die Contact-Point-Menge unverändert bleiben muss. |
pollIntervalMs | 1000 | Wie oft der Seed-Provider gepollt wird. |
maxWaitMs | 60000 | Gesamtbudget; wird es überschritten, wirft die Phase. |
requiredContactPoints | 1 | Wie viele Contact Points eine stabile Beobachtung mindestens enthalten muss. |
selfElectionGraceMs | 10000 | Wie lange der gewählte Node wartet, bevor er einen Cluster bildet. |
Dieselben Schlüssel unter actor-ts.cluster.bootstrap.*, mit der
üblichen Präzedenz — explizite Optionen > HOCON > eingebaute
Defaults:
actor-ts.cluster.bootstrap { stable-margin = 5s poll-interval = 1s max-wait = 60s required-contact-points = 3 self-election-grace = 10s
discovery { method = "kubernetes" service-name = "my-app" }}Der discovery-Unterblock wird von jedem bootstrapCluster-Aufruf
gelesen, nicht nur vom Stable-Observation-Pfad: Er ist die discovery:-Option
in Config-Form, ein Deployment kann die Wahl des Providers und den Namen des
Service also aus dem Anwendungscode herausziehen. Ein method außerhalb von
auto | config | dns | kubernetes wird abgelehnt statt ignoriert. Die
Einstellungen der Provider selbst — DNS-Cache, SRV-Modus, Adress-Pins, eine
statische Seed-Liste — stehen unter
actor-ts.discovery.
requiredContactPoints ist der Wert, den es lohnt anzufassen. Die
Margin fängt Discovery ab, die langsam ist; nur eine Mindestanzahl
fängt Discovery ab, die stabil falsch ist — ein Resolver, der
konsequent zwei von drei Pods liefert, wird sich bereitwillig auf die
falsche Menge einpendeln. Der Default 1 existiert, damit
Einzelknoten-Entwicklung ohne Konfiguration läuft; in Produktion auf die
erwartete Replica-Anzahl setzen.
Was die Optionen weiterreichen und was in HOCON bleibt
Abschnitt betitelt „Was die Optionen weiterreichen und was in HOCON bleibt“Neben den eigenen Einstellungen — Discovery, Stable Observation, Readiness,
newClusterEnabled, die Signal-Handler, der Receptionist — trägt
ClusterBootstrapOptions eine feste Auswahl an Feldern der beiden
Options-Typen, aus denen ein Knoten gebaut wird, unter den Namen, die sie dort
haben:
| Weitergereicht an | Felder |
|---|---|
ActorSystem.create | logger, otelLogs, logSinks, logLevel, config, configFile, persistence |
Cluster.join | host, port, advertisedHost, advertisedPort, transport, die Seeds (seeds oder was die Discovery gefunden hat), roles, appVersion, failureDetector, failureDetectorAutoDown, gossipIntervalMs, downing, splitBrainResolver, shutdownAfterUnsuccessfulJoinMs |
Jedes davon wird nur weitergereicht, wenn es gesetzt ist, und hat dann
Vorrang vor der Konfiguration, wie eine explizite Option überall. Ein
ungesetztes Feld wird nicht als Default weitergereicht: Das System oder der
Join liest seinen eigenen Schlüssel, also entscheiden
actor-ts.cluster.app-version, split-brain-resolver.stable-after oder
actor-ts.logger.sinks.* in der Datei genau so wie bei einem direkten
Cluster.join.
failureDetectorAutoDown ist das Feld, das man kennen sollte, wenn kein
downing gesetzt ist. Ungesetzt liest der Join
actor-ts.cluster.failure-detector.auto-down, das on ausgeliefert wird:
Der Failure Detector entfernt einen Peer, der über down-after hinaus still
bleibt, und die überlebenden Nodes übernehmen seine Shards und Singletons.
false ist das Opt-out, und im Code gesetzt gewinnt es gegen die Datei,
der Failure Detector parkt den Peer dann stattdessen auf unreachable. Das
Beispiel unten konfiguriert KeepMajority, die Form, die ein
Produktions-Deployment übernehmen sollte: Ohne Strategie entfernt bei einer
echten Partition jede Seite die andere, und beide laufen als zwei Cluster
weiter — siehe Downing-Strategien.
import { ClusterBootstrapOptions, KeepMajority } from 'actor-ts/cluster';
const bootstrapOptions = ClusterBootstrapOptions.create('my-app') .withDiscovery('kubernetes') .withDowning(new KeepMajority()) .withSplitBrainResolver({ stableAfterMs: 20_000 }) .withShutdownAfterUnsuccessfulJoinMs(60_000);Jedes andere Feld von ClusterOptions und ActorSystemOptions — der
φ-Accrual-Detektor, die Seed-Retry- und Tombstone-Timings, die
Beförderungsschwellen, die Grenzen und Timeouts der Leitung, Dead-Letter- und
Diagnose-Einstellungen — ist auf diesem Pfad nur über HOCON erreichbar:
unter actor-ts.cluster.*, actor-ts.remote.* oder im eigenen Block des
Systems setzen, in der application.conf oder über withConfig. Dabei geht
nichts verloren, denn das System und der Join lesen diese Schlüssel selbst,
mit der Präzedenz, die sie bei einem direkten Join haben. Der Bootstrap
gewinnt dadurch, eine kurze Liste dessen zu bleiben, was eine Anwendung im
Code entscheidet — die Identität des Knotens, seine Mitgliedschaft, wie
Ausfälle behandelt werden, die Frist des Joins und wohin die Logs gehen —,
statt einer zweiten Kopie zweier Options-Typen, in der jedes weitergereichte
Feld eine Stelle mehr ist, an die eine Änderung denken muss, und ein
vergessenes Weiterreichen still scheitert. Was HOCON nicht ausdrücken kann —
eine Dispatcher-Instanz, ein Scheduler, Startup-Tasks —, braucht
ActorSystem.create und Cluster.join direkt. Das Config-Profil, das keine
Datei für sich selbst wählen kann, folgt weiterhin ACTOR_TS_PROFILE, und
die reference.conf des Projekts, die Secrets-Datei und die .env-Datei
folgen ACTOR_TS_REFERENCE_CONFIG, ACTOR_TS_SECRETS_CONF und
ACTOR_TS_ENV_FILE.
Die eigene Adresse des Knotens
Abschnitt betitelt „Die eigene Adresse des Knotens“Die Wahl ordnet nach der Adresse dieses Knotens, also löst der Bootstrap die
Adresse auf, bevor er irgendetwas beobachtet — aus den Schichten, die
Cluster.join liest, mit den Umgebungsvariablen ganz unten:
explizite Optionen > actor-ts.remote.tcp.* > CLUSTER_HOST / POD_IP / HOSTNAME, CLUSTER_PORT > 0.0.0.0, 2552Ein Port in der application.conf gewinnt also gegen CLUSTER_PORT, und die
Variable antwortet weiterhin auf einem Knoten, dessen Datei keinen nennt: Die
reference.conf liefert keines der beiden Leaves aus, eine unkonfigurierte
Datei lässt die Schicht also leer. Die Identität, die Peers wählen —
advertised-host / advertised-port im selben Block —, wird genauso
aufgelöst, und die Wahl, der Seed-Filter und die Discovery verwenden sie alle
vor dem Join; die Adresse, auf der ein Knoten gewählt wird, ist also die, die
er ankündigt. Siehe
actor-ts.remote.
Auf Readiness warten
Abschnitt betitelt „Auf Readiness warten“Ein aufgelöstes bootstrapCluster bedeutet ein bereites Cluster:
Dieser Knoten ist volles Mitglied (up), und mindestens
minimum-members Mitglieder sind up. Wird das innerhalb des Budgets
nicht erreicht, fährt der Bootstrap die Coordinated-Shutdown-Pipeline
und lehnt mit einem ClusterReadyTimeoutError ab, der Self-Status,
Up-Zähler und die Messlatte nennt — er löst nie für einen Knoten auf,
der noch joining ist.
const bootstrapOptions = ClusterBootstrapOptions.create('my-app') .withHost(process.env.POD_IP!) .withDiscovery('kubernetes') .withStableObservation(true) .withAwaitReady({ minimumMembers: 3, timeoutMs: 30_000 });const node = await bootstrapCluster(bootstrapOptions);node.formedNewCluster; // false — joined an existing cluster rather than founding oneawaitReady nimmt true (Default — mit dem berechneten Budget warten),
false oder 0 (nicht warten), eine Zahl (das Budget in ms) oder das
Options-Objekt oben. Ungesetzte Felder fallen auf HOCON und dann auf das
berechnete Budget durch:
| Feld | Default | Was |
|---|---|---|
minimumMembers | 1 | Wenigste up-Mitglieder — self eingeschlossen —, bevor das Cluster als bereit gilt. Wie requiredContactPoints dimensionieren: auf die Replica-Anzahl. |
timeoutMs | abgeleitet | await-ready, wenn gesetzt; sonst self-election-grace + 5 s hinter Stable Observation mit new-cluster-enabled an — das Budget, an dem die Readiness jedes Knotens tatsächlich hängt, Gewinner oder nicht — sonst flache 5 s. |
actor-ts.cluster.bootstrap { minimum-members = 3 # await-ready = 30s # unset selects the grace-aware computed default}Dasselbe Warten gibt es eigenständig — nach einem von Hand verdrahteten
Cluster.join oder später im Prozess, vor einem
Rebalancing-empfindlichen Schritt:
await cluster.awaitReady({ minimumMembers: 3, timeoutMs: 30_000 });cluster.isReady(); // synchronous probe of the same predicatecluster.selfMember(); // this node's own record, tombstone includedcluster.selfElected; // true — this node founded its clusterOhne timeoutMs wartet das Promise unbegrenzt, wie
system.whenTerminated() — überall dort mit einer Deadline paaren, wo
das Cluster legitim ausbleiben kann; ein Knoten, der das Cluster
verlassen hat oder entfernt wurde, wird nie bereit, und ein Warten, das
noch aussteht, wenn der Join aufgibt, lehnt sofort ab. Readiness heißt hier
bewusst Mitgliedschaft: App-registrierte Readiness-Checks (das
Aggregat des /ready-Endpoints) können von Initialisierung abhängen,
die erst nach dem Bootstrap läuft — auf sie zu warten könnte genau den
Aufruf verklemmen, der zuerst kommt. /ready bleibt die Sicht des Load
Balancers; awaitReady ist die prozessinterne.
Das alte Fire-and-forget-Verhalten liefert awaitReady: false plus ein
eigenes cluster.awaitReady().catch(…).
Verbunden mit der eigenen Frist des Joins
Abschnitt betitelt „Verbunden mit der eigenen Frist des Joins“Jeder Cluster.join kann eine eigene Frist tragen,
actor-ts.cluster.shutdown-after-unsuccessful-join,
und der Join unter dem Bootstrap ist keine Ausnahme. Beide sind
ausdrücklich miteinander verbunden:
awaitReadyläuft zuerst ab — die Ablehnung von oben. Die Pipeline läuft mitClusterJoinUnsuccessfulReason, dem Grund, den auch das Aufgeben übergibt, also erkennt ein Shutdown-Task einen gescheiterten Join an einem einzigen Grund, egal welche Frist abgelaufen ist. Das Scheitern wird auf Error geloggt, bevor dieser Lauf beginnt — unterexit-process = onbeendet der Lauf den Prozess, bevor die Ablehnung den Aufrufer erreichen kann —, und der Lauf endet nie mit0: Mitexit-code = 0endet er mit1.shutdown()auf einem Knoten, der gestartet ist, übergibt weiterhinClusterLeavingReason.- Das Aufgeben kommt zuerst — das Warten endet sofort. Der Bootstrap
wartet auf die Pipeline, die das Aufgeben gestartet hat, und lehnt mit
einem
ClusterReadyTimeoutErrorab, deractor-ts.cluster.shutdown-after-unsuccessful-joinnennt und dessen Frist alstimeoutMsträgt. awaitReady: falseoder0— das Aufgeben ist die einzige Frist, die bleibt, sobaldbootstrapClusterzurückgekehrt ist.- Hinter Stable Observation mit
new-cluster-enabledan wird ein Aufgeben, dasself-election-grace+ 5 s — das berechnete Budget von oben — nicht überschreitet, vor dem Join mit einemOptionsErrorabgelehnt, der beide Schlüssel nennt. Jeder Knoten außer dem gewählten wartet diese Frist ab, ohne dass ihn etwas befördern kann, und gäbe auf einem Cluster auf, der gerade entsteht. Istnew-cluster-enabledaus, wird niemand gewählt und keine Frist läuft, also wird auch kein Aufgeben ihretwegen abgelehnt.
Die Uhr des Aufgebens startet beim Join, also laufen Discovery und Stable Observation vorher. Setze es in HOCON, wo jeder Knoten des Deployments denselben Wert liest:
actor-ts.cluster.shutdown-after-unsuccessful-join = 60soder auf den Bootstrap-Optionen, die Vorrang vor der Datei haben und den Join nur erreichen, wenn sie gesetzt sind:
const bootstrapOptions = ClusterBootstrapOptions.create('my-app') .withDiscovery('kubernetes') .withShutdownAfterUnsuccessfulJoinMs(60_000);So oder so prüft die Ablehnung hinter Stable Observation die Frist, die der
Join scharf schaltet: Ein explizites 0 über einer Datei, die eine setzt,
lässt nichts abzulehnen.
Einen Cluster gründen: nur beim ersten Start
Abschnitt betitelt „Einen Cluster gründen: nur beim ersten Start“Ein gebootstrappter Knoten, der niemanden zum Beitreten findet, gründet einen Cluster — auf dem einfachen Pfad sofort, hinter der Stable Observation nach der Wahl-Grace. Beim ersten Start eines Deployments ist das richtig, irgendwer muss es tun, und bei jedem Start danach ist es das Split-Brain: Ein Knoten, den eine Partition, ein Discovery-Ausfall oder eine DNS-Antwort, die der Pod-Readiness hinterherhinkt, von seinen Peers abschneidet, kommt als Gründer eines zweiten Clusters neben dem laufenden hoch.
actor-ts.cluster.bootstrap.new-cluster-enabled ist der Weg, auf dem ein
Deployment sagt, dass der Cluster jetzt existiert:
actor-ts.cluster.bootstrap.new-cluster-enabled = offAus wählt sich kein gebootstrappter Knoten selbst — die Policy, die der Join
bekommt, ist auf beiden Pfaden 'never' —, und ein explizites seeds: [], das
„ich bin der erste Knoten“ sagt, wird mit einem OptionsError abgelehnt. Ein
Knoten, der niemanden findet, bleibt joining: Unter dem Default-awaitReady
scheitert der Start mit ClusterReadyTimeoutError und baut das System ab, mit
awaitReady: false löst er auf und wartet darauf, dass ein Leader ihn
befördert. Ein existierender Cluster befördert den Neuankömmling genau wie
vorher — aus verbietet das Gründen, nicht das Beitreten.
Der Schlüssel wird mit on ausgeliefert, damit ein erster Start und
Einzelknoten-Entwicklung nichts brauchen, und jeder Start loggt eine Warnung,
solange er an ist: Die Erst-Deploy-Einstellung, die in Produktion an bleibt,
ist genau der Fall, für den es den Schlüssel gibt. withNewClusterEnabled(…)
im Code gewinnt über den Schlüssel, wie jede Option.
Die Stable Observation selbst hat im Block keinen Schalter, und das ist eine
Entscheidung, keine Lücke. Sie einzuschalten ändert, was bootstrapCluster
dem aufrufenden Code verspricht: Jeder Start wartet mindestens
stable-margin, ein Start, dessen Discovery nie zur Ruhe kommt, scheitert
nach max-wait, statt beizutreten, und mit new-cluster-enabled an wächst
das Readiness-Budget um die Wahl-Grace. Das sind Eigenschaften des
Startpfads, um den eine Anwendung
herumgeschrieben ist, also bleibt der Schalter neben diesem Code
(withStableObservation), und die fünf Timings sind Konfiguration, weil sie
eine Phase einstellen, die der Code gewählt hat. Was ein Deployment aus einer
Datei heraus sagen muss, ist, ob ein Knoten überhaupt einen Cluster gründen
darf — und das ist dieser Schlüssel.
Was die Phase verweigert
Abschnitt betitelt „Was die Phase verweigert“Bootstrap oder einfacher Seed-Join?
Abschnitt betitelt „Bootstrap oder einfacher Seed-Join?“| Situation | Wahl |
|---|---|
| Feste, bekannte Adressen; ein festgelegter erster Node | Einfacher Seed-Join. |
| Lokale Entwicklung, ein Node | Einfacher Seed-Join — die leere Seed-Liste heißt bereits „ich bin der erste”. |
| Nodes starten gleichzeitig mit dynamischen Adressen (K8s Deployment, Autoscaling-Gruppe) | Bootstrap. |
| Jeder Node bekommt dieselbe Seed-Liste | Bootstrap — siehe unten. |
Die letzte Zeile übersieht man leicht. Cluster filtert diesen Node aus
seiner eigenen Seed-Liste, also bleibt — wenn jeder Node jeden Node
listet — keinem Node die leere Liste, die die gewöhnliche
Selbstwahl braucht. Niemand wird up, niemand wird Leader, niemand wird
je befördert: der Cluster steht in joining fest. Die Wahl ist das, was
die Symmetrie bricht.
- Startlatenz. Mindestens
stableMarginMs, bei einem echten Kaltstart zusätzlichselfElectionGraceMs(einmalig, von einem Node). Der Beitritt zu einem bestehenden Cluster ist nicht betroffen — die Frist läuft dort nie ab. - Discovery-Last. Ein
lookup()propollIntervalMspro Node, bis die Menge stabil ist. Der Takt ist bewusst konstant statt mit Backoff: ein wachsendes Intervall würde die Stable Margin an driftenden Punkten abtasten, und die eingesparte Last — höchstens ein paar Dutzend Lookups pro Node — wiegt die schwächere Garantie nicht auf.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Beitritt und Seeds — der Join-Handshake, den diese Phase füttert.
- Discovery-Überblick — die Seed-Provider, die die Beobachtung pollt.
- Downing-Strategien — Split-Brain-Auflösung, nachdem der Cluster steht.
- Weakly-up — teilweiser Fortschritt, während die Konvergenz noch aussteht.
