PKR-Lab

60040 - Helm-Charts im TECH-Cluster — Hintergründe

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60040-helm-charts-tech.md

Helm-Charts im TECH-Cluster — Hintergründe

Begründungen zu argocd/apps/tech/*/values.yaml, zu den Chart-Templates und den Dockerfiles der TECH-Apps. Bedienung der Apps steht in
den Docs unter 3-apps-workloads/. Themen mit eigenem Doc: Monitoring in 60060, lldap in
60070, carplay-api in 60080, pacman in
60090, der MDM-Stack in 600d0. PROD-Apps stehen in 60050.


Gemeinsame Muster

Scheduling auf controlplane-1 (Toleration und bevorzugte Affinity)

Planung: 400a0. controlplane-1 trägt den weichen Taint capulus.homeserver/protected=true:PreferNoSchedule, damit ungepinnte Pods den Node meiden. Eine App, die dort laufen soll, bekommt zwei Werte in der values.yaml:

Wert Inhalt Begründung
tolerations capulus.homeserver/protected, Exists, PreferNoSchedule Hebt den Score-Malus des Taints für diese App auf
affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution Gewicht 100 auf kubernetes.io/hostname In [controlplane-1] Zieht die App dorthin, ohne sie festzunageln. Fällt controlplane-1 aus, weicht sie auf controlplane-0 aus

Kein nodeSelector: Ein hartes Pinning hielte die App bei Ausfall von controlplane-1 in Pending. Pods wandern erst, wenn sie neu gestartet werden (Rollout nach der Wertänderung), laufende Pods werden nicht verschoben. Die Charts brauchen dafür tolerations und affinity im Pod-Template. In pacman fehlten die Felder und wurden ergänzt.

HPA und replicas: null

Speicher: local-path, NAS und Squash

Root-Container und runAsNonRoot

Diese Images laufen bewusst als root oder brauchen einen Root-Start, ein erzwungenes runAsNonRoot/runAsUser bricht sie:

App Grund
uptime-kuma Das Image hat kein USER und erwartet root: Der Entrypoint (/app/extra/entrypoint.sh) chownt /app/data selbst nach $PUID:$PGID und wechselt danach per setpriv. Mit erzwungenem Nicht-root-Start scheitert der chown immer mit „Operation not permitted“, unabhängig von StorageClass und Volume-Ownership. PUID/PGID steuern den Privilege-Drop (läuft am Ende als 1000:1000).
uptime-kuma (CORS) Die Website ruft die Status-Page-API im Browser ab, Kuma sendet dafür keine CORS-Header. Die Middleware uptime-kuma-cors am öffentlichen Ingress erlaubt nur die Website-Ursprünge und nur lesende Methoden. Ohne sie bleibt der Live-Status auf updates.html leer („nicht abrufbar“), obwohl die Status-Page 200 liefert.
lldap Der Entrypoint startet als root, chownt /app und /data auf UID/GID (Default 1000) und wechselt per gosu (gleiches Muster wie uptime-kuma).
vaultwarden Das offizielle Image läuft als root (kein USER), anders als n8n.
pihole FTL braucht root plus Capabilities (NET_ADMIN/NET_RAW laut Upstream-Doku, auch ohne DHCP), um Port 53 zu binden. Kein drop: ALL mehr: Der Entrypoint braucht das normale Docker-Default-Set (u. a. CHOWN, SETGID, SETUID, FOWNER), um auf den internen pihole-User zu wechseln und Volume-Dateien zu chownen. Mit drop: ALL brach der Start mit einer Kette von „Operation not permitted“ ab. Da der Container ohnehin als root läuft (Single-Tenant-Node), bringt selektives Droppen hier keinen relevanten Gewinn.
pacman Distroless-Image: Das Basis-Image :nonroot hat bereits die numerische UID 65532. USER nonroot (symbolisch) im Dockerfile würde einen nicht-numerischen User in die OCI-Config schreiben, den die runAsNonRoot-Prüfung des kubelet ablehnt („image has non-numeric user (nonroot)“). Das Dockerfile setzt deshalb die numerische UID explizit (USER 65532:65532), das ist derselbe Wert wie der Image-Default.

Seccomp und n8n-Image. Die selbst gebauten und gehärteten Charts (alamos-apager, alamos-relay, carplay-api, cloudflared in TECH und PROD, github-release-watcher, mediamtx, ntfy-bridge, wiki-docs-sync) setzen im Container-securityContext seccompProfile: RuntimeDefault. Containerd wendet ohne diese Angabe kein Seccomp-Profil an. Die Images (Python, cloudflared, mediamtx) wurden vorab lokal unter Dockers Standardprofil, als Nicht-root, mit --read-only und --cap-drop ALL gestartet. Nicht umgestellt sind Charts mit Root-Start oder Fremd-Images (Tabelle oben, außerdem Zammad, Monitoring, Argo Workflows, Semaphore, MinIO, n8n, Nextcloud, Immich und weitere), weil ein Profil dort nur pro App mit Test eingeführt werden kann. Das n8n-Image bekommt kein explizites USER: Es läuft ohnehin als node, und jede Änderung am Dockerfile löst einen Rebuild und Neustart des empfindlichen n8n aus (SQLite auf dem NAS).

Die Dockerfiles von carplay-api und pacman sind Multi-Stage-Builds: Ein statisches Go-Binary kommt auf ein Distroless-Image ohne Shell,
Paketmanager und libc — nichts, was ein Angreifer im kompromittierten Container nutzen könnte, und nichts zu patchen. Beim carplay-api ist
die im Image gesetzte UID nur der Image-Default, das securityContext des Deployments (runAsUser: 1000) überschreibt sie.

Images und Build

Externe Hosts, Namen und ForwardAuth


Zertifikate und TLS

Warum es kein Wildcard-Zertifikat gibt. Ein echtes *.homeserver ist strukturell unmöglich (Single-Label-TLD, RFC-6125-/
X509_check_host-Regel, unabhängig vom Tool, siehe d0040). Das Zertifikat
homeserver-wildcard-tls (Namespace kube-system) enthält deshalb eine explizite dnsNames-Liste, tier-behaftet
(<app>.tech.homeserver, <app>.prod.homeserver). Ein neuer Host braucht einen Eintrag dort plus Commit. Das ist inhärent zur
fehlenden Wildcard-Fähigkeit, nicht spezifisch für cert-manager.

Stelle Begründung
cert-manager statt manuellem Ablauf Ersetzt „SAN-Liste live aus dem Cluster ziehen, mit openssl signieren, kubeseal“ und das committete SealedSecret. cert-manager erneuert vor Ablauf (duration/renewBefore), der Kalender-Reminder für den 11.11.2028 entfällt. Der alte SealedSecret trug noch die untierte Liste von vor der Domain-Tier-Migration, das war der eigentliche Grund für Hostname-Mismatches auf jedem tier-behafteten Host.
SAN-Einträge, die man leicht vergisst argocd.tech.homeserver (Web-UI per Ingress), der Journal-Upload-Host (Rolle journal_upload: ohne Eintrag scheitert die TLS-Prüfung, und der Upload-Dienst läuft in eine Fehlerschleife), nextcloud.prod.homeserver (originServerName des TECH-Tunnels für die PROD-Hosts, siehe 028), alamos-relay.prod.homeserver und pacman.prod.homeserver (liefen noch in TECH, hatten aber keinen SAN-Eintrag: TLS-Prüfung gegen https://alamos-relay.prod.homeserver scheiterte mit Hostname-Mismatch, Sweep 2026-09-24). Authentik braucht einen Hostnamen (Authelia brauchte wegen einer statischen Cookie-Domain pro Tier zwei), die lldap-Web-UI ist LAN/Tailscale-only.
ClusterIssuer nutzt die bestehende Root-CA Kein SelfSigned-Bootstrap mit neu erzeugter Root-CA (der cert-manager-Standardweg): Das würde eine komplett neue CA erzeugen und auf jedem Client-Gerät einen erneuten Trust-Store-Rollout brauchen. Stattdessen wird die vorhandene CA (rootCA.pem/rootCA-key.pem) einmalig als Kubernetes-Secret importiert, das auf allen Geräten installierte pki/homeserver-root-ca.pem bleibt gültig (Befehl in d0040, „Einmaliger Import“).
CA-Key nicht als SealedSecret Der CA-Key wandert bewusst ins Cluster (cert-manager muss selbst signieren und erneuern können), ist aber höherwertig als ein App-Secret: Ein Leak der Sealed-Secrets-Controller-Keys aus dem Repo darf ihn nicht mit offenlegen. Der Import bleibt ein einmaliger manueller kubectl create secret-Schritt außerhalb von GitOps, das Secret existiert nur im Cluster.
PROD: eigene Intermediate-CA Der PROD-Issuer signiert mit einer PROD-eigenen Intermediate-CA aus der gemeinsamen Root-CA (Entscheidung 0.3, Baustein 4 in 40080). Clients vertrauen weiter nur der Root-CA, kein neuer Trust-Rollout. Der Root-Key verlässt den Rechner nicht, nur der Intermediate-Key liegt in PROD (Secret homeserver-ca-keypair im Namespace cert-manager, einmalig manuell importiert, nie im Repo, auch nicht versiegelt). Das PROD-Zertifikat hat dieselben Secret-/Namespace-Namen (homeserver-wildcard-tls in kube-system), damit das TLSStore unverändert greift, aber nur die *.prod.homeserver-Hosts.
cert-manager-Values CRDs sind Teil des Helm-Release (ArgoCD wendet alles in einem Sync an, kein manueller Vorab-Schritt). Sie bleiben erhalten, falls die App aus ArgoCD entfernt wird: Ein versehentliches Prune soll nicht alle Zertifikatsdefinitionen mitreißen. Die startupapicheck ist deaktiviert: Ihr Job hängt bei jedem Sync ein zusätzliches Job-Objekt an, das manuell aufgeräumt werden müsste (ArgoCD prunt abgeschlossene Jobs nicht), die echte Verifikation läuft über den Status des Certificate.
TLSStore default Der Name default ist keine freie Wahl, sondern die von Traefik reservierte Sonder-Ressource, die für jeden Router ohne explizites TLSStore gilt. Ohne sie fiele jeder Router auf Traefiks selbstsigniertes Zertifikat zurück (Browser-Warnung trotz Verschlüsselung). Bewusst ein TLSStore statt spec.tls.secretName an jedem der ~36 Ingress-Objekte.
Globaler HTTP→HTTPS-Redirect (ports.web.http.redirections) Ohne ihn beantwortet Traefik Port 80 für jeden Host weiterhin unverschlüsselt, das Zertifikat greift nur auf :443. Sichtbar wurde das über Authentik: Dessen ForwardAuth-Middleware berechnet die Rückkehr-URL dynamisch aus dem tatsächlichen Request-Schema (trustForwardHeader: true), kam der Request über Port 80, blieb der gesamte Login-Flow samt Auth-Cookie auf Klartext-HTTP. cloudflared zeigt für externe Hosts ohnehin auf den HTTPS-Entrypoint und ist vom Redirect nicht betroffen.
Folge des Redirects Der Redirect ist ein 308, und viele Clients folgen ihm bei POST nicht (urllib, systemd-journal-upload, ansible.builtin.uri). Deshalb sind https:// und der Port Pflicht bei journal_upload, semaphore_api_base, vmagent und der Zammad-URL des github-release-watcher (60020).

Traefik-Metriken und HelmChartConfig

coredns-custom

k3s-CoreDNS lädt automatisch alle ConfigMap-Keys mit dem Suffix .server aus diesem ConfigMap (import /etc/coredns/custom/*.server).
Hintergrund: dnsmasq auf dem Host (192.168.178.94:53) löst *.homeserver für LAN und Tailscale auf, Cluster-Pods nutzen aber CoreDNS
(10.43.0.10) und kennen die Domain nicht. Anfragen an z. B. semaphore.tech.homeserver scheiterten mit „no such host“. Der Block
leitet alle *.homeserver-Anfragen an dnsmasq weiter.

Zweites CoreDNS-Replikat per HPA (hpa.yaml im selben Verzeichnis): Das Deployment coredns gehört dem k3s-Addon-Controller (objectset.rio.cattle.io/owner-name: coredns, Manifest /var/lib/rancher/k3s/server/manifests/coredns.yaml mit replicas: 1). Eine manuelle Skalierung oder ein Patch durch ArgoCD kann beim erneuten Anwenden des Addons zurückgesetzt werden, und ArgoCD würde ein fremd verwaltetes Deployment nicht übernehmen. Ein HPA mit minReplicas: 2 und maxReplicas: 2 stellt die Anzahl nach jedem Zurücksetzen binnen Sekunden wieder her, ohne das Addon zu berühren. Wohin das zweite Replikat kommt, regeln die vorhandenen topologySpreadConstraints des Addons (kubernetes.io/hostname, DoNotSchedule): immer auf den anderen Server. Fällt controlplane-1 aus, bleibt das zweite Replikat Pending und der erste läuft weiter. Die CPU-Schwelle (100 %) spielt wegen min == max keine Rolle, die Metrik ist nur nötig, weil ein HPA mindestens eine verlangt.

cloudflared


Apps

alamos-apager und alamos-relay

argo-workflows und garage

github-release-watcher

Benachrichtigungen: ntfy, ntfy-bridge

alert-caller

Telefon-Alarm im Cluster, Bedienung in 10020. Der Anrufer wurde zuerst für eine externe VM gebaut (60020), läuft aber vorerst als Pod,
weil ein Ausfall des Clusters (und damit kein Anruf) bewusst in Kauf genommen wird.

mediamtx

n8n

ollama

Der Cluster-Chart argocd/apps/tech/ollama/ ist seit 2026-10-31 entfernt. Ollama läuft auf dem Desktop-PC, der Code liegt im n8n-Chart unter argocd/apps/tech/n8n/ollama-pc/ (300g0). Warum es so gebaut ist:

pihole

DNS ist ein NodePort, damit der Host-dnsmasq (capulus-ansible/roles/dnsmasq) über <network_static_ip>:<nodePort> dorthin weiterleiten kann,
ohne den Router anzufassen. Der Port muss pihole_dns_nodeport in capulus-ansible/group_vars/all.yml entsprechen. Pi-hole v6/FTL braucht
kein separates dnsmasq im Container. Die Fritz!Box bleibt der eigentliche Resolver und ist DHCP-Server, Pi-hole filtert nur. Zu Root und Capabilities
siehe oben.

Update-Strategie und Readiness (seit dem Vorfall 50020):

semaphore

uptime-kuma

vaultwarden

zammad

ticket-gate

headlamp

Kleinere Charts

Chart Hinweis
headlamp Eigene HPA, siehe „HPA und replicas: null“. Anmeldung und Rechte: Abschnitt „headlamp“ oben.
kubeseal-webgui autoFetchCert lässt die App den Public Key beim Start selbst holen, statt ein statisches Zertifikat einzubetten. apiUrl ist die URL, die der Browser für das API-Backend nutzt und muss zum Ingress-Hostnamen passen, sonst funktioniert die UI nicht. Alle Keys liegen unter kubeseal-webgui:, weil das der Dependency-Name ist.
sealed-secrets Vorhersagbarer Service-Name, damit die kubeseal-CLI und kubeseal-webgui den Controller ohne zusätzliche Flags finden.
logging Der Grafana-Sidecar im Namespace monitoring sucht nach ConfigMaps mit dem Datasource-Label (ohne searchNamespace nur im eigenen Namespace monitoring), darüber findet er die VictoriaLogs-Datasource. Der Collector hängt bei einer URL ohne Pfad automatisch /insert/native an.
immich-storage, nas-storage Siehe „Speicher“ oben.