HTTP-Endpunkte
Der Management-Server stellt einen kleinen Satz operativer
Endpunkte bereit. Die meisten sind read-only; die Admin-Endpunkte
(/cluster/down, /cluster/leave) sind Opt-in und standardmäßig aus.
Sicherheit (security audit #8): die read-only-Endpunkte legen dennoch
interne Topologie offen — Member-Adressen (host:port), Rollen, die
Anwendungsversion, die jedes Mitglied nennt, den Leader
und die Shard-Map. Behandle den Management-Server als sensibel: binde ihn an
ein internes Interface und schütze ihn mit den Optionen ipAllowlist (und/oder
auth) von managementRoutes(...), statt ihn öffentlich zu exponieren.
Health-Probes
Abschnitt betitelt „Health-Probes“GET /health
Abschnitt betitelt „GET /health“Liveness — ist dieser Prozess fundamental gesund?
GET /health→ 200 OK{ "status": "UP", "checks": [ { "name": "actor-system", "status": true } ]}503 mit { "status": "DOWN", ... }, wenn ein Liveness-Check
fehlschlägt. Siehe
Health Checks.
GET /ready
Abschnitt betitelt „GET /ready“Readiness — sollte dieser Pod Traffic bekommen?
GET /ready→ 200 OK{ "status": "UP", "clusterReady": true, "checks": [ { "name": "cluster-membership", "status": true }, { "name": "cluster-transport", "status": true }, { "name": "database", "status": true } ]}Das checks-Array enthält jeden Readiness-Check auf der Registry
des Systems — die
eingebauten Checks
des Frameworks (cluster-membership und cluster-transport, dazu
startup und je benanntem Typ ein shard-region:<type>, wo konfiguriert)
und alles, was du registriert hast.
clusterReady ist das Ergebnis von cluster-membership selbst, aus
diesem Array zurückgelesen statt separat berechnet: es ist also
false, bis der lokale Node Up erreicht, und true, wenn es gar
keinen Cluster gibt. 503, wenn ein Check fehlschlägt.
Die beiden Probe-Pfade verschieben
Abschnitt betitelt „Die beiden Probe-Pfade verschieben“/health und /ready sind Defaults, keine festen Routen. Beide
sind ein einzelnes Pfadsegment und im Code wie aus einer
Config-Datei setzbar:
actor-ts.management { liveness-path = "alive" readiness-path = "serving"}Ein Wert mit / wird beim Bauen der Routen mit einem
OptionsError abgelehnt, denn path() entfernt nur
umschließende Slashes — aus "k8s/ready" würde ein Segment mit
einem Slash darin, das auf keine URL passt und den Endpunkt
lautlos verschwinden lässt. Wie die Segmente auch heißen: halte
die Probe-Pfade in K8s im Gleichschritt damit, ein Manifest wird
von nichts gegengeprüft.
Cluster-Info
Abschnitt betitelt „Cluster-Info“Verfügbar, wenn ein cluster an managementRoutes übergeben
wurde.
GET /cluster/members
Abschnitt betitelt „GET /cluster/members“GET /cluster/members→ 200 OK{ "members": [ { "address": "my-app@10.0.0.5:2552", "status": "up", "version": 1710000000001, "roles": ["compute"], "appVersion": "2.4.0" }, ... ], "self": "my-app@10.0.0.5:2552"}Voller Membership-Snapshot. Adressen haben die Form
system@host:port, die auch POST /cluster/down erwartet.
version ist die logische Uhr des Mitglieds: Sie beginnt bei der
Wanduhrzeit seines Joins in Millisekunden — so überholt ein unter
derselben Adresse neu gestarteter Node den Tombstone, den sein
vorheriger Lauf hinterlassen hat — und steigt mit jedem Statuswechsel
um eins. Nützlich für:
- Manuelle Cluster-Zustand-Checks während Incidents.
- Externe Dashboards, die den Cluster visualisieren.
- Tests, die das Cluster-Joining verifizieren.
appVersion ist die Anwendungsversion, die das Mitglied nennt —
actor-ts.cluster.app-version
oder withAppVersion(...) im Code —, und daran lässt sich ein Rolling Update
ablesen: welcher Node welches Release fährt. Das Feld steht nur bei einem
Mitglied, das eine Version nennt, und fehlt sonst, statt null zu sein — ein
Mitglied, das ohne Version neu startet, steht ohne da, nicht mit der seines
vorigen Laufs —; es ist ein Label und nicht mehr — nichts platziert, routet
oder downt danach.
Wie der Rest dieses Endpunkts wird es jedem ausgeliefert, der den Port
erreicht, solange managementRoutes(...) kein auth bekommt
(#971) — es fügt also
dem, was ein nicht authentifizierter Aufrufer erfährt, das Release jedes
Nodes hinzu.
GET /cluster/leader
Abschnitt betitelt „GET /cluster/leader“GET /cluster/leader→ 200 OK{ "leader": "my-app@10.0.0.5:2552", "isSelf": true }Die Adresse des Leaders plus isSelf (ist der lokale Node der
Leader). leader ist null, bevor ein Leader gewählt wurde.
Nützlich zum Monitoring von Leader-Wechseln.
GET /cluster/shards?type=<typeName>
Abschnitt betitelt „GET /cluster/shards?type=<typeName>“GET /cluster/shards?type=cart→ 200 OK{ "typeName": "cart", "leader": "my-app@10.0.0.5:2552", "version": 7, "takenAt": 1710000000000, "regions": [ { "key": "my-app@10.0.0.5:2552|/system/cluster/sharding/region-cart", "address": "my-app@10.0.0.5:2552", "path": "/system/cluster/sharding/region-cart", "proxy": false, "shards": [0, 1, 2, ..., 33] }, ... ], "shardHome": [ { "shard": 0, "regionKey": "my-app@10.0.0.5:2552|/system/cluster/sharding/region-cart" }, ... ]}Zeigt die Shard-zu-Region-Allokation für einen sharded Typ. Nutze für:
- Verifizieren gleichmäßiger Verteilung nach einem Rebalance.
- Diagnostizieren heißer Regionen (eine Region mit zu vielen Shards).
- Manuelle Rebalance-Trigger in der Entwicklung.
Woher die Antwort kommt. Der Node antwortet aus
ClusterSharding.shardMap(typeName) — der letzten Karte, die der
Coordinator an die Region dieses Nodes gesendet hat. Dafür ist keine
Konfiguration nötig: keine DistributedData-Extension, kein
coordinatorStateStore, kein Round-Trip zum Leader. Die einzige
Voraussetzung ist, dass der antwortende Node an dem Typ teilnimmt —
also sharding.start(...) oder sharding.startProxy(...) dafür
aufgerufen hat —, denn der Coordinator sendet nur an Regionen, die
sich registriert haben. Ein Node, der cart nie erwähnt hat, hat
nichts zu berichten und antwortet mit 404.
Früher las dieser Endpunkt den DistributedData-Snapshot des
Coordinators, wodurch eine 200 in einer Standardkonfiguration
unerreichbar war: nichts im Framework startet diese Extension, und der
Snapshot wird nur geschrieben, wenn man sich per
coordinatorStateStore dafür entscheidet. Der Store existiert
weiterhin und bleibt optional — er verkürzt den Leader-Failover —,
aber dieser Endpunkt hängt nicht mehr davon ab.
Den Body lesen:
versionzählt Broadcasts des Coordinators, keine Shard-Zuweisungen — eine Erhöhung pro Publish, und ein Publish fasst einen Schwung Verschiebungen zusammen. Vergleiche den Wert über zwei Abfragen, um „die Karte hat sich bewegt“ von „die Karte ist unverändert“ zu unterscheiden.takenAtundleaderstempelt der antwortende Node beim Eintreffen der Karte, zwei Nodes können also dieselbeversionmit leicht verschiedenen Zeitstempeln melden.regions[].keyist<Adresse>|<Region-Pfad>, derselbe Key, denshardHome[].regionKeyverwendet. Eine Region, die nichts hostet, steht trotzdem in der Liste, mit leeremshards— „registriert und ohne Shards“ ist die interessante Hälfte einer Rebalance-Frage.- Eine 200 mit leerem
shardHomeist normal und kein Fehler:regionsfüllt sich, sobald sich Regionen registrieren, während ein Shard erst dann ein Zuhause bekommt, wenn eine Entity darin adressiert wird.
Metriken
Abschnitt betitelt „Metriken“GET /metrics
Abschnitt betitelt „GET /metrics“Opt-in via enableMetricsEndpoint: true.
GET /metrics→ 200 OKContent-Type: text/plain; version=0.0.4; charset=utf-8
# HELP actor_messages_processed_total ...# TYPE actor_messages_processed_total counteractor_messages_processed_total{class="Worker",path="..."} 12345...Prometheus-Textformat. Siehe Prometheus-Exporter.
Antwortet stattdessen mit 503, wenn die installierte
MetricsRegistry sich nicht über collect() zurücklesen lässt —
die prom-client-Bridge
ist die eine im Framework, die das nicht kann, weil sie ihre
Schreibvorgänge an prom-client weiterleitet und keinen Snapshot
behält:
GET /metrics→ 503 Service Unavailable
metrics endpoint unavailable: the installed MetricsRegistry does notsupport collect() — ...Ein 200 mit leerem Body wäre schlimmer als der Fehler: eine leere
Exposition ist ein gültiger Scrape, also verbucht Prometheus das
Target als erreichbar, und jede Serie des Frameworks hört still auf
zu existieren. Die Prüfung läuft pro Request, weil die Registry zu
jedem Zeitpunkt im Leben des Systems ausgetauscht werden kann.
Admin (Opt-in)
Abschnitt betitelt „Admin (Opt-in)“POST /cluster/leave
Abschnitt betitelt „POST /cluster/leave“Opt-in via enableLeaveEndpoint: true.
POST /cluster/leave→ 202 AcceptedleavingDer 202-Body ist das Klartext-Wort leaving (kein JSON) — der
Leave ist Fire-and-forget.
Löst einen Graceful Cluster-Leave aus. Der Node wechselt auf
leaving und meldet das den Peers, die er erreicht; sie führen ihn
als removed, und seine Shards werden umverteilt. Das Actor-System
selbst läuft weiter: Der Endpunkt ruft cluster.leave() auf und
sonst nichts.
Nutze für:
- Pod-Außerbetriebnahme vor einem Rolling Update.
- Manuellen Node-Out während Incidents.
Hinter Authentifizierung gaten — jeder mit Portzugriff kann deinen Node drainen.
POST /cluster/down
Abschnitt betitelt „POST /cluster/down“Opt-in via enableDownEndpoint: true oder
actor-ts.management.enable-down-endpoint = on in HOCON.
POST /cluster/down{ "address": "my-app@10.0.0.5:2552" }
→ 202 Accepted{ "downed": "my-app@10.0.0.5:2552" }Gibt 202 mit { downed } zurück, wenn das Mitglied gedownt wurde,
oder 404, wenn die Adresse unbekannt oder bereits terminal ist.
Force-downt ein Mitglied per Adresse, in der Sicht des Nodes, den du
aufrufst: Es wird dort als down und removed angekündigt und als
Tombstone behalten, und Gossip trägt das Entfernen zu den
Mitgliedern, die dieser Node noch erreicht. Das verteilt die Shards
des Mitglieds neu und gibt seinen entfernten Watchern ihr
Terminated. Das Target selbst wird nicht benachrichtigt (#940): Es
läuft weiter, samt seinen Actors — stoppe es also zuerst oder stell
sicher, dass es weg ist, bevor du es downst.
Das ist der Weg aus dem Opt-out. Unter dem Default — keine
Downing-Strategie, actor-ts.cluster.failure-detector.auto-down = on
— löscht der Failure Detector ein stilles Mitglied selbst, sobald er
es für down erklärt, und der Endpunkt antwortet danach meist mit
404 dafür. Mit zwei oder mehr Überlebenden kann der Gossip eines
anderen Überlebenden das gelöschte Mitglied allerdings als
unreachable zurückbringen, bis der Detector es erneut entfernt,
und ein Aufruf in diesem Fenster findet es und antwortet mit 202.
Unter auto-down = off parkt der Failure Detector ein stilles
Mitglied auf unreachable, und der Node loggt eine Warnung, die das
Mitglied und diesen Endpunkt nennt; nur ein Operator, eine Strategie
oder der eigene Neustart des Nodes auf derselben Adresse entfernt es.
Nutze für:
- Entfernen eines abgestürzten Mitglieds, das der Failure
Detector unter
auto-down = offgeparkt hat, ohne konfigurierte Downing-Strategie. Wurde der Node seitdem auf derselben Adresse neu gestartet, hat der Cluster den geparkten Lauf schon beendet, und der Eintrag unter dieser Adresse ist der neue Prozess:GET /cluster/memberszeigt ihn wieder aufupmit neuererversion. Ihn dann zu downen entfernt den gesunden Lauf, der nicht benachrichtigt wird und außerhalb des Clusters weiterläuft. - Eine Partition von Hand auflösen unter
auto-down = offohne Strategie: Downe die Mitglieder der anderen Seite von der Seite aus, die du behältst, und stoppe die Prozesse auf der Seite, die du aufgibst, denn sie werden nicht benachrichtigt. Unter dem Default gibt es bis dahin nichts mehr aufzulösen — jede Seite hat die andere beidown-afterentfernt und läuft als eigener Cluster weiter; konfigurierelease-majorityoder eine andere Downing-Strategie, damit stattdessen eine Seite gewinnt. - Entfernen eines Mitglieds, das eine konfigurierte Strategie geparkt gelassen hat, weil sie zu keinem Urteil gekommen ist.
Hochrisiko-Endpunkt — hinter Auth + Audit-Logs gaten.
Eigene Routen
Abschnitt betitelt „Eigene Routen“import { path, get, concat, completeJson } from 'actor-ts/http';import { managementRoutes } from 'actor-ts/management';
const baseRoutes = managementRoutes(system, cluster);
const customRoutes = concat( baseRoutes, path('admin', get(async () => completeJson(200, { appVersion: '1.2.3' })), ),);
await system.http(port, { host }).bind(customRoutes);managementRoutes(system, cluster, options) gibt die Basis-Routen
zurück; kombiniere mit eigenen via concat. Nützlich, um
app-spezifische Admin-Endpunkte neben dem Standard-Satz
hinzuzufügen.
Response-Format
Abschnitt betitelt „Response-Format“Die Read-Endpunkte (/health, /ready, /cluster/members,
/cluster/leader, /cluster/shards) und /cluster/down geben
JSON zurück. /metrics liefert Prometheus-text/plain, und
/cluster/leave gibt den Klartext-Body leaving zurück.
Fehler sind Klartext-Bodies (das complete(status, message) des
Frameworks), kein strukturiertes Objekt — z. B. ergibt ein fehlender
type-Query-Param ein 400, dessen Body missing query param \type“ ist.
Status-Codes folgen HTTP-Konventionen: 200 für Reads, 202 Accepted
für die Admin-Aktionen (/cluster/leave, /cluster/down), 4xx für
Client-Fehler (404, wenn eine /cluster/down-Adresse unbekannt ist)
und 503, wenn Cluster oder ein Health-Check nicht verfügbar ist.
Authentifizierung & IP-Allowlist (#312)
Abschnitt betitelt „Authentifizierung & IP-Allowlist (#312)“Die privilegierten Endpunkte (/cluster/down, /cluster/leave,
/cluster/members, /cluster/shards, /metrics) akzeptieren
standardmäßig anonyme Requests. Das ist nur sicher, wenn der
Management-Port auf einem netzwerkisolierten Bind sitzt
(separater Service, anderer Port, 127.0.0.1-only) oder hinter
einem Reverse-Proxy, der die Auth für dich übernimmt.
Für Produktions-Deployments, die Management-Endpunkte einem
breiteren Netz exponieren, hänge die mitgelieferten Middlewares
über managementRoutes(system, cluster, { auth, ipAllowlist })
an:
import { BearerTokenAuth, IpAllowlist,} from 'actor-ts/http';import { managementRoutes,} from 'actor-ts/management';
const routes = managementRoutes(system, cluster, { enableLeaveEndpoint: true, enableDownEndpoint: true, enableMetricsEndpoint: true, // Shared-Secret-Bearer-Token (Rotation über mehrere Einträge). auth: BearerTokenAuth({ tokens: [process.env.MGMT_TOKEN!], realm: 'my-app-mgmt', }), // Netzwerk-Level-Fence — nur Requests aus diesen CIDRs // erreichen die Anwendung überhaupt. ipAllowlist: IpAllowlist({ allow: ['10.0.0.0/8', '127.0.0.1/32'], // Hinter einem Reverse-Proxy: benenne die Proxys — die // Client-Adresse wird dann vom Socket-Ende der // Forwarded-Kette nach innen aufgelöst. Ohne das liest der // Default den Socket-Peer, und der ist hinter einem Proxy // der Proxy. // trustedProxies: ['10.9.9.0/24'], }),});Policy-Trennung:
authwrappt die privilegierte Teilmenge (/cluster/*,/metrics)./healthund/readybleiben anonym — Kubernetes- Liveness-/Readiness-Probes können nicht so leicht einen Authorization-Header mitschicken. SetzeauthProtectHealth: true, wenn dein Deployment garantiert, dass die Probes Credentials präsentieren können.ipAllowlistwrappt JEDEN Endpunkt inklusive/healthund/ready. Netzwerk-Level-Isolation ist unabhängig davon, wer authentifiziert ist.
Fehlermodi:
- Fehlender / falscher
Authorization-Header →401 UnauthorizedmitWWW-Authenticate: Bearer realm="...". - Client-IP außerhalb der Allowlist (oder unauflösbar) →
403 Forbidden.
Die Middlewares sind general-purpose — du kannst sie auch
außerhalb des Management-Subtrees über den
withMiddleware(mw, route)-Builder einsetzen.
Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Management — Überblick — das größere Bild.
- Health Checks — Custom-Check-Registrierung.
- Cluster — Überblick — die
Membership-Semantik hinter den
/cluster/*-Endpunkten. - Kubernetes-Deployment — das K8s-Rezept, das diese Endpunkte nutzt.
- Prometheus-Exporter — die Details des Metrik-Formats.
