Zum Inhalt springen
Deutsch

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.

apiVersion: v1
kind: ServiceAccount
metadata:
name: actor-ts
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: actor-ts-pod-reader
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: actor-ts
subjects:
- kind: ServiceAccount
name: actor-ts
roleRef:
kind: Role
name: actor-ts-pod-reader
apiGroup: rbac.authorization.k8s.io
---
apiVersion: v1
kind: Service
metadata:
name: actor-ts-cluster
spec:
clusterIP: None # headless — DNS liefert Pod-IPs
selector:
app: actor-ts
ports:
- name: cluster
port: 2552
targetPort: 2552
---
apiVersion: v1
kind: Service
metadata:
name: actor-ts
spec:
selector:
app: actor-ts
ports:
- name: http
port: 80
targetPort: 8080
- name: management
port: 8558
targetPort: 8558
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: actor-ts
spec:
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"]
ServiceAccount: actor-ts
Role: actor-ts-pod-reader # get + list pods
RoleBinding: bindet beides

Der 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.

clusterIP: None

Ein 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.

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.

NimmWann
StatefulSetStabile 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.
DeploymentPod-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: 30

K8s 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:
exec:
command: ["/bin/sh", "-c", "sleep 10"]

Kritisch für saubere Rolling Updates. Der Ablauf:

  1. K8s markiert den Pod als terminating und startet den preStop-Hook parallel zur Load-Balancer-Deregistrierung.
  2. sleep 10 — gibt dem Load Balancer Zeit, keinen neuen Traffic mehr an diesen Pod zu schicken.
  3. Nach dem Sleep sendet K8s SIGTERM.
  4. 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.

readinessProbe: /ready
livenessProbe: /health

Die 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 ist up) und cluster-transport (er ist nicht von jedem Peer abgeschnitten), dazu startup, solange Startup-Tasks laufen. Damit ein Knoten aus der Rotation bleibt, bis seine Shard-Regionen registriert sind, nenne die Typen in actor-ts.sharding.healthcheck.names (siehe die eingebauten Checks). App-spezifische Checks — Datenbank erreichbar, Dependencies warm — kommen mit healthChecksOf(system).addReadiness dazu. Prozessintern gated Cluster.bootstrap genauso: actor-ts.cluster.bootstrap.minimum-members (oder awaitReady: { 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 wie required-contact-points. Auf einem System mit Startup-Tasks ist er außerdem durch startup abgesichert, 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 ist actor-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 Phase persistence-start abläuft. Sollen beide unabhängig voneinander starten, fahre die Datenbank zuerst hoch, oder setze autoStart im Persistence-Behaviour auf false und lass die erste persistierte Nachricht sie finden.
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-Discovery
const 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-Endpunkte
const mgmtRoutes = managementRoutes(system, cluster);
await system.http(8558).bind(mgmtRoutes);
// 3. App-HTTP-Server
const http = system.extension(HttpExtensionId);
await http.newServerAt('0.0.0.0', 8080).bind(routes);
// 4. Laufen, bis das Kubelet Stopp sagt, dann geordnet herunterfahren
await system.runUntilTerminated();

Vier Schritte in der Reihenfolge:

  1. Cluster-Join mit Seed-Discovery — der K8s-API-Seed-Provider fragt Pods ab, die app=actor-ts matchen, und nutzt deren IPs als Seeds. Auf dem ersten Pod ist die Seed-Liste nur er selbst (der Auto-Promote-to-Leader-Pfad).
  2. Management-Endpunkte — /health + /ready für die K8s-Probes, /cluster/members zum Debuggen.
  3. App-HTTP — deine Routes, getrennter Port vom Management.
  4. 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 der service-unbind-Phase registriert und Cluster.join den Leave in cluster-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.

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: v1
kind: Secret
metadata:
name: actor-ts-secrets-conf
type: Opaque
stringData:
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: true
volumes:
- 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 in application.conf substituierte Variable wird nur zurückgehalten, wenn ihr Key ein Geheimnis benennt.
  • Ein Image, jede Umgebung. ACTOR_TS_PROFILE legt den Block profiles.production der application.conf — und der Secrets-Datei — über deren Wurzel, und ein unbekanntes Profil verhindert den Start.
  • Einmal gelesen, beim Start. Kubernetes aktualisiert ein eingebundenes Secret an 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.conf keinen Default, damit sein Fehlen dort scheitert, wo es gelesen wird, statt mit einem Platzhalter zu laufen.

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.

Terminal-Fenster
kubectl rollout restart statefulset/actor-ts

Für jeden Pod, der Reihe nach (StatefulSet) oder beliebig (Deployment):

  1. K8s markiert den Pod als terminating + startet preStop.
  2. 10-Sekunden-LB-Drain.
  3. SIGTERM kommt an.
  4. Coordinated Shutdown läuft:
    • Keine neuen HTTP-Requests mehr annehmen (service-unbind, verdrahtet von bind()).
    • 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 von Cluster.join).
    • Das Actor-System terminieren (actor-system-terminate).
  5. runUntilTerminated() löst auf, seine Signal-Handler gehen ab, und der Prozess beendet sich sauber.
  6. K8s startet einen neuen Pod aus dem neuen Image.
  7. 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.