Kubernetes-Deployment
Kubernetes ist das häufigste Deployment-Ziel. Das Framework verträgt sich gut mit K8s, sobald ein paar Dinge sitzen: stabile Identität (für stateful Actors), Seed-Discovery (damit Nodes sich finden) und ein sauberer Shutdown-Pfad (damit Rolling Updates keinen Traffic verlieren).
Diese Seite ist ein funktionierendes Rezept — kopieren, anpassen, deployen.
Das vollständige Manifest
Abschnitt betitelt „Das vollständige Manifest“apiVersion: v1kind: ServiceAccountmetadata: name: actor-ts---apiVersion: rbac.authorization.k8s.io/v1kind: Rolemetadata: name: actor-ts-pod-readerrules: - apiGroups: [""] resources: ["pods"] verbs: ["get", "list"]---apiVersion: rbac.authorization.k8s.io/v1kind: RoleBindingmetadata: name: actor-tssubjects: - kind: ServiceAccount name: actor-tsroleRef: kind: Role name: actor-ts-pod-reader apiGroup: rbac.authorization.k8s.io---apiVersion: v1kind: Servicemetadata: name: actor-ts-clusterspec: clusterIP: None # headless — DNS liefert Pod-IPs selector: app: actor-ts ports: - name: cluster port: 2552 targetPort: 2552---apiVersion: v1kind: Servicemetadata: name: actor-tsspec: selector: app: actor-ts ports: - name: http port: 80 targetPort: 8080 - name: management port: 8558 targetPort: 8558---apiVersion: apps/v1kind: StatefulSetmetadata: name: actor-tsspec: serviceName: actor-ts-cluster replicas: 3 selector: matchLabels: app: actor-ts template: metadata: labels: app: actor-ts spec: serviceAccountName: actor-ts terminationGracePeriodSeconds: 30 containers: - name: app image: ghcr.io/your-org/your-app:1.2.3 ports: - name: cluster containerPort: 2552 - name: http containerPort: 8080 - name: management containerPort: 8558 env: - name: ACTOR_TS_HOSTNAME valueFrom: fieldRef: fieldPath: status.podIP - name: ACTOR_TS_PORT value: "2552" - name: K8S_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: K8S_LABEL_SELECTOR value: "app=actor-ts" - name: DB_PASSWORD valueFrom: secretKeyRef: name: actor-ts-secrets key: db-password readinessProbe: httpGet: path: /ready port: management initialDelaySeconds: 5 periodSeconds: 5 livenessProbe: httpGet: path: /health port: management initialDelaySeconds: 15 periodSeconds: 10 lifecycle: preStop: exec: # LB drainen, bevor SIGTERM die App erreicht command: ["/bin/sh", "-c", "sleep 10"]Was die einzelnen Teile tun
Abschnitt betitelt „Was die einzelnen Teile tun“ServiceAccount + RBAC
Abschnitt betitelt „ServiceAccount + RBAC“ServiceAccount: actor-tsRole: actor-ts-pod-reader # get + list podsRoleBinding: bindet beidesDer K8s-API-Seed-Provider muss Pods listen können, die einem Label-Selector entsprechen, um Peers zu finden. Ohne dieses RBAC-Grant bekommt der Seed-Provider 403 und der Cluster bildet sich nie.
Headless Service für Cluster-Gossip
Abschnitt betitelt „Headless Service für Cluster-Gossip“clusterIP: NoneEin headless Service liefert die Pod-IPs direkt per DNS (keine ClusterIP-Virtual-Address). Nützlich, wenn Nodes stabile, direkte Peer-Identitäten brauchen — die Heartbeats des Failure Detectors zielen auf spezifische Pod-IPs, nicht auf eine load-balancete Abstraktion.
Regulärer Service für Traffic
Abschnitt betitelt „Regulärer Service für Traffic“clusterIP: <default>Ein normaler Service für HTTP und den Management-Endpunkt — die profitieren von Load Balancing. Cluster-Traffic geht über den Headless Service, App-Traffic über diesen.
StatefulSet vs Deployment
Abschnitt betitelt „StatefulSet vs Deployment“| Nimm | Wann |
|---|---|
| StatefulSet | Stabile Pod-Namen (actor-ts-0, actor-ts-1, …). Nützlich, wenn du vorhersagbare Identität für Entity-Placement willst oder wenn pro-Pod Persistent Volumes gemountet werden. |
| Deployment | Pod-Namen sind zufällig. Okay, wenn deine App stateless ist (keine pro-Pod-Identität erforderlich) und Persistence extern liegt (Cassandra-Journal, geteilter S3-Snapshot-Store). |
Für sharded Actors mit remember-entities = true auf pro-Pod
Persistent Volumes ist StatefulSet die richtige Wahl. Für
extern-persistierten State (Cluster gegen ein geteiltes
Postgres/Cassandra) ist Deployment in Ordnung und einfacher.
terminationGracePeriodSeconds
Abschnitt betitelt „terminationGracePeriodSeconds“terminationGracePeriodSeconds: 30K8s sendet SIGTERM, wartet dann diese Zeitspanne vor SIGKILL. Dimensioniert nach:
- HTTP-Drain — typischerweise 5-10 s.
- Cluster-Leave-Gossip — 5-15 s für Konvergenz.
- Journal-Flush — abhängig vom Journal.
30 s sind ein vernünftiger Default. Erhöhe, wenn dein Cluster groß oder das Failure-Detector-Fenster lang ist.
preStop-Sleep
Abschnitt betitelt „preStop-Sleep“preStop: exec: command: ["/bin/sh", "-c", "sleep 10"]Kritisch für saubere Rolling Updates. Der Ablauf:
- K8s markiert den Pod als terminating und startet den
preStop-Hook parallel zur Load-Balancer-Deregistrierung. sleep 10— gibt dem Load Balancer Zeit, keinen neuen Traffic mehr an diesen Pod zu schicken.- Nach dem Sleep sendet K8s SIGTERM.
- Die Coordinated-Shutdown-Hooks der App drainen in-flight Requests, verlassen den Cluster usw.
Ohne den Sleep läuft SIGTERM gegen die LB-Deregistrierung — in-flight Requests können “draining”-Antworten sehen.
Readiness- + Liveness-Probes
Abschnitt betitelt „Readiness- + Liveness-Probes“readinessProbe: /readylivenessProbe: /healthDie Management-Routen des Frameworks stellen diese Endpunkte bereit.
/ready— „soll ein Load Balancer diesem Pod Traffic schicken?” Bereits durch die Checks des Frameworks abgesichert:cluster-membership(dieser Knoten istup) undcluster-transport(er ist nicht von jedem Peer abgeschnitten), dazustartup, solange Startup-Tasks laufen. Damit ein Knoten aus der Rotation bleibt, bis seine Shard-Regionen registriert sind, nenne die Typen inactor-ts.sharding.healthcheck.names(siehe die eingebauten Checks). App-spezifische Checks — Datenbank erreichbar, Dependencies warm — kommen mithealthChecksOf(system).addReadinessdazu. Prozessintern gatedCluster.bootstrapgenauso:actor-ts.cluster.bootstrap.minimum-members(oderawaitReady: { minimumMembers }im Code) sorgt dafür, dass ein aufgelöster Bootstrap nichts Geringeres bedeutet als „das Cluster hat seine erwartete Größe erreicht” — auf die Replica-Anzahl setzen, genau wierequired-contact-points. Auf einem System mit Startup-Tasks ist er außerdem durchstartupabgesichert, der false bleibt, bis der Startup-Graph jede Phase durchlaufen hat — ein Pod, dessen Startup-Tasks noch nicht fertig sind, bekommt keinen Traffic, auch wenn sein Port schon gebunden ist./health— „würde ein Neustart dieses Pods helfen?” Schlägt er fehl, startet K8s den Pod neu; er hängt deshalb von nichts außerhalb des Prozesses ab — der einzige Liveness-Check des Frameworks istactor-system. Niemals eine Datenbank oder einen Downstream-Dienst hier eintragen: ein gemeinsamer Ausfall würde die ganze Flotte neu starten, und die Neustarts würden nichts reparieren.- Ein fehlgeschlagener Start beendet den Prozess, statt ihn
nur nicht bereit zu lassen. Das System fährt sich über den
Coordinated Shutdown selbst herunter,
runUntilTerminated()rejected mit dem Fehler des Starts, und der Container endet mit einem Status ungleich null — Kubernetes startet ihn also neu, und ein Rollout, dessen Start nicht gelingen kann, bleibt beim ersten Pod stehen, statt zu bedienen, bis die erste Anfrage kommt, die gebraucht hätte, was der Start nicht geschafft hat. - Die Persistence-Stores öffnen während des Starts, also lässt ein
falscher Connection-String — ein falscher Host, ein falsches
Passwort, ein Treiber, der im Image fehlt — den Pod schon beim
Booten scheitern, nicht erst bei seiner ersten persistierten
Nachricht (Stores beim Start
öffnen) — außer
hinter dem Object-Storage-Snapshot-Store und dem
Object-Storage-Durable-State-Store, die vorab nichts öffnen, sodass
ein unerreichbarer Bucket stattdessen ihre erste Operation scheitern
lässt. Die Kehrseite: Eine Datenbank, die erst nach der App erreichbar wird,
schickt den Pod in
CrashLoopBackOff, bis sie es ist — jeder Versuch scheitert, wenn der Store abgewiesen wird oder das Budget von 30 s der Phasepersistence-startabläuft. Sollen beide unabhängig voneinander starten, fahre die Datenbank zuerst hoch, oder setzeautoStartim Persistence-Behaviour auf false und lass die erste persistierte Nachricht sie finden.
App-seitige Verdrahtung
Abschnitt betitelt „App-seitige Verdrahtung“import { ActorSystem } from 'actor-ts';import { Cluster, ClusterOptions } from 'actor-ts/cluster';import { KubernetesApiSeedProvider, KubernetesApiSeedProviderOptions } from 'actor-ts/discovery';import { managementRoutes } from 'actor-ts/management';
const system = ActorSystem.create('my-app');
// 1. Cluster-Join mit K8s-API-Seed-Discoveryconst kubernetesApiSeedProviderOptions = KubernetesApiSeedProviderOptions.create() .withNamespace(process.env.K8S_NAMESPACE!) .withServiceName(process.env.K8S_SERVICE_NAME!) .withSystemName(system.name) .withPort(2552);const seeds = await new KubernetesApiSeedProvider(kubernetesApiSeedProviderOptions).lookup();
const clusterOptions = ClusterOptions.create() .withHost(process.env.ACTOR_TS_HOSTNAME!) .withPort(parseInt(process.env.ACTOR_TS_PORT!)) .withSeeds(seeds.map(a => a.toString())) .withRoles(['compute']);const cluster = await Cluster.join(system, clusterOptions);
// 2. Management-Endpunkteconst mgmtRoutes = managementRoutes(system, cluster);await system.http(8558).bind(mgmtRoutes);
// 3. App-HTTP-Serverconst http = system.extension(HttpExtensionId);await http.newServerAt('0.0.0.0', 8080).bind(routes);
// 4. Laufen, bis das Kubelet Stopp sagt, dann geordnet herunterfahrenawait system.runUntilTerminated();Vier Schritte in der Reihenfolge:
- Cluster-Join mit Seed-Discovery — der K8s-API-Seed-Provider
fragt Pods ab, die
app=actor-tsmatchen, und nutzt deren IPs als Seeds. Auf dem ersten Pod ist die Seed-Liste nur er selbst (der Auto-Promote-to-Leader-Pfad). - Management-Endpunkte —
/health+/readyfür die K8s-Probes,/cluster/memberszum Debuggen. - App-HTTP — deine Routes, getrennter Port vom Management.
- Bis zum Terminieren laufen — installiert die
SIGTERM/SIGINT-Handler, blockiert, führt dann die Pipeline aus und
löst auf, wenn das System unten ist. Es gibt keinen separaten
Teardown-Schritt zu schreiben: beide
bind()-Aufrufe haben ihr Unbind in derservice-unbind-Phase registriert undCluster.joinden Leave incluster-leave— der Pod fällt also aus den Service-Endpoints und aus dem Cluster, bevor die Actors stoppen.
Siehe Discovery — Kubernetes API für die vollständigen Optionen des Seed-Providers.
Secrets als eingebundene Datei
Abschnitt betitelt „Secrets als eingebundene Datei“Das Manifest oben reicht DB_PASSWORD als Umgebungsvariable an den
Prozess. Die Secrets-Datei
hält Credentials ganz aus der Umgebung heraus: ein Secret, als Datei
eingebunden und über ACTOR_TS_SECRETS_CONF benannt, das
Profil gewählt über
ACTOR_TS_PROFILE:
apiVersion: v1kind: Secretmetadata: name: actor-ts-secrets-conftype: OpaquestringData: secrets.conf: | my-app.db.password = "s3cr3t"---# The StatefulSet above, under spec.template.spec:containers: - name: app env: - name: ACTOR_TS_PROFILE value: "production" - name: ACTOR_TS_SECRETS_CONF value: /etc/actor-ts/secrets.conf volumeMounts: - name: secrets-conf mountPath: /etc/actor-ts readOnly: truevolumes: - name: secrets-conf secret: secretName: actor-ts-secrets-conf- Zurückgehalten, egal wie es heißt. Jeder Wert, den die Datei
setzt, erscheint im Konfigurations-Dump und im DevTools-Panel als
<redacted>, auch in Worker-Threads; eine inapplication.confsubstituierte Variable wird nur zurückgehalten, wenn ihr Key ein Geheimnis benennt. - Ein Image, jede Umgebung.
ACTOR_TS_PROFILElegt den Blockprofiles.productionderapplication.conf— und der Secrets-Datei — über deren Wurzel, und ein unbekanntes Profil verhindert den Start. - Einmal gelesen, beim Start. Kubernetes aktualisiert ein
eingebundenes
Secretan Ort und Stelle, aber die Konfiguration wird nicht neu gelesen; rolle die Pods, um eine Änderung zu übernehmen. - Eine fehlende Datei ist kein Fehler. Ohne das Mount ist die
Secrets-Schicht einfach leer, und die Kopfzeile des Dumps sagt, dass die
Datei nicht gefunden wurde. Gib einem Credential in
application.confkeinen Default, damit sein Fehlen dort scheitert, wo es gelesen wird, statt mit einem Platzhalter zu laufen.
Das erste Deployment und jedes danach
Abschnitt betitelt „Das erste Deployment und jedes danach“Starten die Pods über Cluster.bootstrap statt über den von Hand verdrahteten
Join oben, brauchen der allererste Rollout und jeder Rollout danach eine
Einstellung verschieden. Beim ersten muss irgendein Pod den Cluster gründen —
so wird actor-ts.cluster.bootstrap.new-cluster-enabled ausgeliefert.
Sobald der Cluster existiert, schalte es ab. Aus einer Variablen gelesen,
bleibt das eine Ein-Zeilen-Änderung am Manifest statt eines neuen Images:
actor-ts.cluster.bootstrap.new-cluster-enabled = ${?ACTOR_TS_NEW_CLUSTER_ENABLED}# The StatefulSet above, under spec.template.spec.containers[0].env —# added after the first rollout has formed the cluster:- name: ACTOR_TS_NEW_CLUSTER_ENABLED value: "off"Von da an scheitert ein Pod, der seine Peers beim Start nicht erreicht — eine geänderte NetworkPolicy, ein Schluckauf des API-Servers, eine DNS-Antwort, die der Pod-Readiness hinterherhinkt —, an seinem Readiness-Warten und wird neu gestartet, statt als Gründer eines zweiten Clusters neben dem laufenden hochzukommen. Jeder Start loggt eine Warnung, solange der Schlüssel noch an ist; ein Deployment, das nie umgeschaltet hat, sagt es also in seinen eigenen Logs. Siehe Cluster-Bootstrap.
Rolling Updates
Abschnitt betitelt „Rolling Updates“kubectl rollout restart statefulset/actor-tsFür jeden Pod, der Reihe nach (StatefulSet) oder beliebig (Deployment):
- K8s markiert den Pod als terminating + startet
preStop. - 10-Sekunden-LB-Drain.
- SIGTERM kommt an.
- Coordinated Shutdown läuft:
- Keine neuen HTTP-Requests mehr annehmen (
service-unbind, verdrahtet vonbind()). - In-flight Requests drainen (
service-requests-done, deins). - Broker-Verbindungen schließen (
service-stop, verdrahtet von jedem Broker-Actor). cluster.leave()ausgeben (cluster-leave, verdrahtet vonCluster.join).- Das Actor-System terminieren (
actor-system-terminate).
- Keine neuen HTTP-Requests mehr annehmen (
runUntilTerminated()löst auf, seine Signal-Handler gehen ab, und der Prozess beendet sich sauber.- K8s startet einen neuen Pod aus dem neuen Image.
- Der neue Pod tritt dem Cluster via Seed-Provider bei.
Für sharded Entities passiert das Rebalancing automatisch — die Shards des gehenden Nodes werden neu zugeteilt; neue Entities respawnen auf dem neuen Pod aus dem Journal.
Wohin als nächstes
Abschnitt betitelt „Wohin als nächstes“- Operations-Überblick — das Gesamtbild aller Produktionsbelange.
- Discovery — Kubernetes API — die Optionen des Seed-Providers.
- Coordinated Shutdown — die DSL für phased Shutdown.
- Management-Endpunkte — die /health- und /ready-Endpunkte, gegen die K8s-Probes laufen.
- Cluster-Sicherheit — TLS + Auth für den Cluster-Transport.
- Rolling Migration — schema-brechende Änderungen während eines Rollouts.
