PKR-Lab

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:

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:

Single-Writer/Standalone-Datenspeicher:

Vom Upstream-Chart selbst als nicht skalierbar markiert:

Monitoring-Komponenten, die einzeln laufen müssen:


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.