b0040 - Horizontale Autoskalierung (HPA)
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/b-kubernetes-gitops/b0040-hpa-autoscaling.md
Horizontale Autoskalierung (HPA)
Auslöser: Immich stürzte bei vielen/großen Uploads ab (OOMKilled), und
Kubernetes hat nicht automatisch mehr Pods gestartet — schlicht weil
nirgends ein HorizontalPodAutoscaler (HPA) existierte. Dieses Dokument
beschreibt, welche Apps in diesem Repo einen HPA bekommen haben, mit
welchen Schwellenwerten, und — genauso wichtig — welche Apps bewusst
keinen bekommen haben und warum.
Kurzfassung: was ein HPA hier lösen kann und was nicht
Ein HPA reagiert auf viele gleichzeitige Anfragen/Jobs, indem er
weitere Pods startet, sobald der CPU-/RAM-Verbrauch der laufenden Pods
einen Schwellenwert überschreitet. Er hilft nicht dabei, dass eine
einzelne schwere Anfrage (z. B. ein einzelnes sehr großes Video) mehr
RAM bekommt, als der Container-resources.limits erlaubt — dafür muss
das Limit selbst erhöht werden. Für Immich konkret: viele parallele
Uploads verteilen sich jetzt auf mehrere immich-server-Pods, ein
einzelnes 4K-Video, das für sich allein schon >4Gi RAM braucht, crasht
trotzdem (siehe server.resources.limits in
argocd/apps/prod/immich/values.yaml).
Zwei technische Voraussetzungen, die überall gleich gelöst wurden
1. ArgoCD selfHeal vs. HPA — das replicas-Problem
Das Root-ApplicationSet
(argocd/bootstrap/root-applicationset.yaml)
läuft mit syncPolicy.automated.selfHeal: true und
syncOptions: [ServerSideApply=true]. Ohne Gegenmaßnahme würde ArgoCD bei
jedem Sync die von git/Helm vorgegebene, statische replicas-Zahl wieder
herstellen und damit den HPA sofort zurückdrehen, sobald er hochskaliert.
Zwei Varianten, je nachdem, ob wir das Deployment-Template selbst
besitzen:
-
Eigene (hand-geschriebene) Chart-Templates (immich, cloudflared,
nextcloud, wikijs, example-whoami, ntfy-bridge,
mediamtx):replicas:wird im Template komplett weggelassen, sobald
Autoscaling aktiv ist:spec: {{- if not .Values.autoscaling.enabled }} replicas: {{ .Values.replicaCount }} {{- end }}Da das Feld dann in keinem von ArgoCD angewendeten Manifest mehr
auftaucht, beansprucht ArgoCDs Server-Side-Apply-Field-Manager dafür nie
die Ownerschaft — der vom HPA gesetzte Wert bleibt unangetastet. -
Fremde Chart-Abhängigkeiten ohne eigenes Template
(headlamp, kubeseal-webgui, zammadnginx/railsserver): Hier
rendert das Upstream-Template unconditionalreplicas: {{ .Values.replicaCount }}.
Statt den Wert zu entfernen (nicht möglich, fremdes Template), wird er
aufnullgesetzt:replicaCount: null # bzw. zammadConfig.<component>.replicas: nullDas rendert zu
replicas:(leer). Unter Server-Side-Apply bedeutet ein
explizit aufnullgesetztes Feld "ich gebe die Ownership für dieses
Feld ab", nicht "setze es auf null" — der vom HPA verwaltete Wert bleibt
dadurch ebenfalls unangetastet. (OhneServerSideApply=truewürde dieser
Trick nicht zuverlässig funktionieren — mit reinem Client-Side-Apply
hätte man stattdessenignoreDifferences: [{jsonPointers: ["/spec/replicas"]}]
auf Application-Ebene gebraucht.)
Bekannte Ausnahme: zammad-websocket hat keinen HPA bekommen —
siehe Ausgeschlossene Apps unten. Der
Upstream-Chart kodiert dort replicas: 1 fest als Literal (nicht über
einen Values-Key steuerbar), es gibt also nichts, das man auf null
setzen könnte.
2. ReadWriteOnce-Storage + mehrere Replicas → erzwungene Co-Location
Mehrere Apps mounten ihre Foto-/Datei-Bibliothek als
ReadWriteOnce-PVC (NFS) — RWO heißt: gleichzeitig mountbar auf einem
Node, nicht auf mehreren. Skaliert der HPA auf >1 Replica hoch und der
Scheduler setzt eine neue Replica auf einen anderen Node als die
bestehende, bliebe der Pod im ContainerCreating hängen
(Multi-Attach-Fehler).
Betroffene Apps (immich server/machine-learning, nextcloud) bekamen
deshalb eine zusätzliche, fest verdrahtete podAffinity, die alle
Replicas zwingend auf denselben Node wie bereits laufende Pods derselben
Komponente setzt:
affinity:
podAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels: { <selector-labels der Komponente> }
topologyKey: kubernetes.io/hostname
Der bisher konfigurierbare *.affinity-Values-Key wurde für diese
Komponenten entfernt (war überall ohnehin leer {}), um zu verhindern,
dass eine spätere manuelle Konfiguration diese Pflicht-Regel
versehentlich überschreibt.
Bei Nextcloud ist das nur sicher, weil die App bereits ein eigenes Redis
für verteiltes Datei-Locking nutzt (siehe
../3-apps-workloads/300b0-nextcloud.md) — geteilter Storage + mehrere
App-Pods funktioniert bei Nextcloud nur, wenn das Locking nicht auch noch
lokal im Dateisystem passiert.
Wiki.js, die Bridges und die Test-Apps brauchen diese Affinity nicht —
sie haben schlicht kein PVC (Wiki.js speichert alles in PostgreSQL).
Apps mit aktivem HPA
| App | Komponente | Replicas | Trigger | Besonderheit |
|---|---|---|---|---|
| immich | server |
1–3 | CPU 75% / RAM 80% | podAffinity (RWO-Library) |
| immich | machine-learning |
1–2 | CPU 75% / RAM 80% | podAffinity (RWO-Model-Cache); niedrigeres Max, da jede Inferenz-Instanz bis zu 4 Kerne/4Gi allein beansprucht |
| nextcloud | App-Tier | 1–2 | CPU 75% / RAM 80% | podAffinity (RWO html/data); sicher dank Redis-Locking |
| wikijs | App-Tier | 1–3 | CPU 75% / RAM 80% | kein PVC, kein Affinity-Trick nötig |
| cloudflared | — | 2–4 | CPU 70% | Minimum bleibt 2 (zwei unabhängige Edge-Verbindungen) |
| example-whoami | — | 1–3 | CPU 70% | Test-App |
| ntfy-bridge | — | 1–3 | CPU 75% | stateless Webhook-Übersetzer |
| mediamtx | — | 1–2 | CPU 75% | hilft nur bei neuen Verbindungen — ein laufender RTMP/RTSP-Stream bleibt am ursprünglichen Pod hängen (kein Rebalancing) |
| headlamp | — | 1–3 | CPU 75% | hand-geschriebener HPA, Upstream-Chart hat kein natives Autoscaling |
| kubeseal-webgui | — | 1–2 | CPU 75% | hand-geschriebener HPA |
| zammad | nginx |
1–3 | CPU 70% | hand-geschriebener HPA |
| zammad | railsserver |
1–3 | CPU 75% / RAM 80% | hand-geschriebener HPA |
Alle Schwellenwerte sind bewusst konservativ gewählt (CPU 70–75%, RAM 80%)
— lieber eine Replica zu früh dazu als spät, da Homeserver aktuell der
einzige durchgehend laufende Node ist (siehe
../2-betrieb-hardware/20020-cluster-power-manager.md).
Ausgeschlossene Apps (kein HPA)
SQLite/embedded Datenbank auf RWO-Storage — mehrere Pods würden sich
dieselbe DB-Datei zerschießen:
- n8n, paperless-ngx, vaultwarden (alle explizit SQLite,
siehe jeweilige Doku) - ntfy (Cache-/Auth-Datei auf der PVC)
- uptime-kuma (zusätzlich hart auf den Homeserver-Node gepinnt)
- semaphore (embedded BoltDB)
- monitoring/Grafana — läuft mit
persistence.type: pvc(RWO,
local-path) und ohne externe DB-Anbindung, also embedded SQLite;
der Grafana-Subchart hat zwar nativesautoscaling.*, das würde hier
aber dieselbe Klasse von Problem erzeugen wie bei Vaultwarden
Single-Writer/Standalone-Datenspeicher:
- garage (Single-Node-Modus mit
replication_factor = 1und SQLite-Metadaten,
mehrere Replikas bräuchten ein Layout über mehrere Knoten, nicht HPA) - alle internen
postgresql/redis-Deployments (immich, nextcloud,
wikijs, zammad) — Single-Writer-Datenbanken, teils zusätzlich per
nodeAffinityauflocal-path-Storage gepinnt
Vom Upstream-Chart selbst als nicht skalierbar markiert:
- zammad
scheduler— Background-Job-Runner, doppelte Ausführung würde
Jobs duplizieren - zammad
websocket— der Chart kodiertreplicas: 1 # Not scalable, may only run once per cluster.fest, vermutlich weil Echtzeit-Events
intern ohne gemeinsamen Broker zwischen mehreren Prozessen verteilt
werden. Kein Values-Key vorhanden, den man aufnullsetzen könnte —
selbst wenn man einen HPA hinzufügt, würde ArgoCDsselfHealdie
Replica-Zahl bei jedem Sync auf 1 zurücksetzen, UND die App könnte
funktional kaputtgehen.
Monitoring-Komponenten, die einzeln laufen müssen:
- vmsingle (nicht-geclusterte TSDB), vmagent/vmalert (VM-Operator-CRDs —
doppelte Replicas ohne Sharding würden Scrapes/Alerts duplizieren),
Alertmanager
Neue/geänderte Vendoring-Artefakte
kubeseal-webgui und zammad hatten bisher keine vendorten
Chart-Abhängigkeiten (Chart.lock/charts/*.tgz) — ArgoCD hat die beim
Sync live vom Upstream-Repo/OCI-Registry gezogen. Beim Validieren der
HPA-Änderungen (helm dependency build) wurden diese Artefakte erzeugt
und committet, analog zum bereits bestehenden Vorgehen bei headlamp
und monitoring. Funktional ändert sich dadurch nichts (die
gepinnte Version in Chart.yaml war schon vorher exakt fixiert) — nur
künftige Versions-Bumps in Chart.yaml brauchen danach zusätzlich
helm dependency update, sonst schlägt der Sync wegen einer
Lock-Datei-Inkonsistenz fehl.
Verifizieren
kubectl -n <namespace> get hpa
kubectl -n <namespace> describe hpa <name>
TARGETS zeigt aktuelle vs. Ziel-Auslastung; REPLICAS die aktuell
laufende Anzahl. Voraussetzung ist ein laufender metrics-server im
Cluster (bereits vorhanden, siehe kubectl top pod/node).
Fehlersuche
kubectl get hpa -A
kubectl -n <ns> describe hpa <name> # Conditions: AbleToScale, ScalingActive, ScalingLimited
kubectl top pods -n <ns>
kubectl -n kube-system get pods -l k8s-app=metrics-server
| Symptom | Ursache | Lösung |
|---|---|---|
TARGETS zeigt <unknown>/70% |
metrics-server liefert keine Werte oder das Deployment hat keine CPU-requests |
kubectl top pods, resources.requests.cpu im Chart setzen |
| HPA skaliert nicht hoch | Auslastung unter dem Schwellenwert, maxReplicas erreicht, Node ohne Platz |
describe hpa, Events, Node-Kapazität |
| HPA skaliert nicht herunter | Stabilisierungsfenster (zum Beispiel 300 s bei kubeseal-webgui), Last schwankt |
warten, behavior.scaleDown prüfen |
| Replikazahl springt zurück (ArgoCD gegen HPA) | replicas steht noch im Template oder in values (statt null/weggelassen) |
Muster aus Voraussetzungen, ignoreDifferences im ApplicationSet |
Pods nach cubi scale auf 0 kommen nicht zurück |
HPA bei 0 Replikas inaktiv, Auto-Sync war an | cubi: Pods wiederherstellen |
FailedGetResourceMetric in den Events |
Pods noch nicht bereit oder Metrik fehlt | einige Minuten warten, metrics-server prüfen |
OOMKilled trotz HPA |
ein einzelner Request braucht mehr Speicher als das Limit | Limit erhöhen, ein HPA hilft nur gegen viele gleichzeitige Anfragen (siehe Kurzfassung) |
Pods Pending nach Hochskalieren |
keine freien Ressourcen oder Node-Selektor | Node-Auslastung, Worker eingeschaltet? (Cluster Power Manager) |
| Subchart-Replikas bleiben fest | Upstream-Template rendert replicas unbedingt |
Wert auf null setzen, siehe Abschnitt „Fremde Chart-Abhängigkeiten“ oben |
Allgemeine Fehlersuche: zentrale Fehlersuche.