Joining und Seeds

Ein Node tritt einem Cluster bei, indem er einen Seed-Node kontaktiert. Der Seed sendet per Gossip seine aktuelle Mitgliedschaftssicht zurück; der Joiner wird als joining hinzugefügt, propagiert per Gossip, und sobald der Leader ihn sieht (plus Konvergenz), wechselt er zu up.

Diese Seite behandelt die Mechanik dieses Handshakes plus die Seed-Discovery-Ebene darüber.

Der einfachste Fall — explizite Seeds

import { ActorSystem, Cluster, ClusterOptions } from 'actor-ts';

const system = ActorSystem.create('my-app');

const clusterOptions = ClusterOptions.create()
  .withHost('10.0.0.5')
  .withPort(2552)
  .withSeeds(['10.0.0.5:2552', '10.0.0.6:2552', '10.0.0.7:2552']);
const cluster = await Cluster.join(
  system,
  clusterOptions,
);

Drei Seeds. Der Joiner kontaktiert sie der Reihe nach, bis einer antwortet. Sobald irgendein Seed akzeptiert, propagiert der Gossip des Clusters das neue Mitglied; Konvergenz zu up geschieht innerhalb weniger Sekunden in einem gesunden Netzwerk.

Die Seed-Liste ist nur ein Bootstrap-Hinweis — sobald der Node beigetreten ist, lernt er alle anderen Peers per Gossip kennen. Seeds müssen nach dem Join nicht mehr besonders sein.

Konfiguration

type ClusterOptionsType = {
  host:                       string;       // Adresse dieses Nodes
  port:                       number;       // TCP-Port dieses Nodes
  seeds?:                     string[];     // Peer-Adressen fürs Bootstrap
  roles?:                     string[];     // Rollen-Tags
  failureDetector?:           Partial<...>;
  transport?:                 Transport;
  gossipIntervalMs?:          number;
  seedRetryIntervalMs?:       number;       // Retry-Intervall, falls kein Seed antwortet
  // ...
};

Die seed-bezogenen Knöpfe:

Einstellung	Standard	Was
seeds	[]	Liste von "host:port"-Strings. Leer = “ich bin der erste”.
seedRetryIntervalMs	3000	Falls kein Seed antwortet, wiederhole die Liste so oft, bis einer antwortet.
selfElection	'immediate'	Wann dieser Node allein einen Cluster bilden darf: 'immediate' (nur bei leerer Seed-Liste), 'never', oder eine Frist in Millisekunden. Wird vom Cluster-Bootstrap gesetzt.

Der erste Node

const clusterOptions = ClusterOptions.create()
  .withHost('0.0.0.0')
  .withPort(2552)
  .withSeeds([]);
const cluster = await Cluster.join(
  system,
  clusterOptions,
);

Eine leere seeds-Liste (oder eine, die komplett unerreichbar ist) bedeutet, dass dieser Node den Cluster selbst bootstrapt. Er befördert sich automatisch zum Leader; künftige Joiner kontaktieren ihn.

Das macht die Single-Node-Entwicklung trivial — keine zu pflegende Seed-Liste. Füge später einen zweiten Node hinzu, indem du ihm die Adresse des ersten als Seed gibst.

Für Produktion bestimme einen Node mit leerer Seed-Liste und gib den übrigen dessen Adresse — oder, besser, nutze den Cluster-Bootstrap, der einen festgelegten ersten Node überflüssig macht.

Die symmetrische Seed-Liste startet nicht kalt

Es liegt nahe, jedem Node dieselbe Liste mit allen Nodes zu geben. Diese Konfiguration bildet nie einen Cluster:

Cluster entfernt die eigene Adresse aus der Seed-Liste, also bleibt bei einer symmetrischen Liste keinem Node die leere Liste, die selfElection: 'immediate' verlangt. Jeder Node bleibt für immer joining; es gibt keinen Leader, und der Leader ist es, der joining → up befördert.

Zwei Auswege:

• Ein festgelegter erster Node mit seeds: [], der Rest zeigt auf ihn. Einfach, aber dieser Node ist beim Start etwas Besonderes — was Container und Autoscaler unhandlich machen.
• Cluster-Bootstrap — jeder Node bekommt dieselbe Konfiguration, und das Framework wählt genau einen aus, der den Gleichstand bricht. Das ist die Wahl, sobald Nodes gleichzeitig starten.

Die Retry-Schleife über seedRetryIntervalMs bleibt wichtig, löst aber ein anderes Problem: einen Seed, der irgendwann erreichbar ist. Ein erstes Mitglied kann sie nicht herbeizaubern.

Seed-Discovery — jenseits einer statischen Liste

Eine hartcodierte Seed-Liste reicht für Tests und kleine Cluster. Für Produktion, in der Nodes dynamische IPs haben (Container, K8s Pods), nutze einen Seed-Provider:

Provider	Wann
Config	Statische Liste (der Fall oben).
DNS	Löst _actor-ts._tcp.example.com SRV-Records auf.
Kubernetes API	Listet Pods, die einem Label-Selector entsprechen.
Aggregate	Fällt durch mehrere Provider durch (z. B. K8s, dann DNS).

import { KubernetesApiSeedProvider, KubernetesApiSeedProviderOptions } from 'actor-ts/discovery';

const kubernetesApiSeedProviderOptions = KubernetesApiSeedProviderOptions.create()
  .withNamespace('default')
  .withServiceName('actor-ts')
  .withPort(2552);
const seedProvider = new KubernetesApiSeedProvider(
  kubernetesApiSeedProviderOptions,
);

const seeds = await seedProvider.discover();

const clusterOptions = ClusterOptions.create()
  .withHost(process.env.POD_IP!)
  .withPort(2552)
  .withSeeds(seeds);
const cluster = await Cluster.join(
  system,
  clusterOptions,
);

Der Provider liefert eine Momentaufnahme von Seed-Adressen; das Framework nutzt sie, um den Join zu bootstrappen. Siehe Discovery-Überblick für das Seed-Provider-Modell.

Den Join-Fortschritt beobachten

import { SelfUp, MemberUp } from 'actor-ts';

cluster.subscribe((evt) => {
  if (evt instanceof SelfUp) {
    console.log(`dieser Node ist jetzt Up`);
  } else if (evt instanceof MemberUp) {
    console.log(`Peer ${evt.member.address} hat Up erreicht`);
  }
});

Zwei zentrale Events:

• SelfUp feuert einmal, wenn dieser Node auf up übergeht. Nützliches Gate, um Arbeit zu starten, die Cluster-Mitgliedschaft erfordert.
• MemberUp feuert jedes Mal, wenn irgendein Mitglied up erreicht.

Für Startup-Logik, die andere Mitglieder braucht (“warte, bis mindestens 3 Nodes up sind, bevor Traffic bedient wird”), zähle MemberUps nach SelfUp.

Was schiefgehen kann

Seeds unerreichbar, sich selbst nicht in der Liste

// ✗ dieser Node ist kein Seed, kein anderer Seed antwortet
const clusterOptions = ClusterOptions.create()
  .withHost('n4')
  .withPort(2552)
  .withSeeds(['n1', 'n2', 'n3']);
Cluster.join(system, clusterOptions);

Der Join wiederholt sich unendlich (auf dem Standard-Loglevel still). Falls die Seed-Liste tatsächlich unerreichbar ist, tritt der Node nie bei. Entweder nimm diesen Node in die Seed-Liste auf (jeder ist ein Seed), oder implementiere Health-Checks, die “kein Cluster beigetreten” als Alert sichtbar machen.

Zwei Cluster bilden sich mit demselben Namen

// Netzwerkpartition direkt beim Start:
// - n1, n2 erreichen sich → bilden Cluster
// - n3 kann sie nicht erreichen → bootstrapt eigenen Cluster
// - Partition heilt → zwei Cluster mit demselben Namen existieren

Sobald die Partition geheilt ist, merged das Gossip-Protokoll die beiden Cluster nicht automatisch — sie sind unabhängig. Mildere das mit einer Downing-Strategie (Downing-Strategien) und mit dem Cluster-Bootstrap, der genau einen Node berechtigt, einen Cluster zu bilden, und gar nicht erst entscheidet, solange Discovery ihre Meinung ändert.

Hostname-vs-IP-Mismatch

// Joiner sieht Seed als `pod-abc-123.cluster.local`
// Seed sieht sich selbst als `10.244.1.5`
// → Gossips Adressvergleich behandelt sie als verschiedene Mitglieder

Die Mitglieder-Identität nutzt die Adresse, die der Node beim Join angegeben hat. Wenn verschiedene Peers verschiedene Adressen für denselben Node sehen (typisch in K8s mit Hostnames), bildet sich der Cluster zwar, aber jeder Node sieht den Peer als Fremden. Verwende den K8s-Seed-Provider, der konsistent auf Pod-IPs auflöst, oder setze host auf die IP statt auf den Hostnamen.

Wohin als Nächstes

• Cluster-Überblick — das größere Bild.
• Cluster-Bootstrap — Stable Observation und Initial-Seed-Wahl für gleichzeitige Starts.
• Weakly-up — Gradual-Join-Semantik für langsame Konvergenz.
• Failure Detector — wie Heartbeats die Mitgliedschaftssicht nach dem Join frisch halten.
• Discovery-Überblick — Seed-Provider für dynamische Umgebungen.
• Downing-Strategien — Split-Brain-Auflösung nach der Cluster-Bildung.