60050 - Helm-Charts im PROD-Cluster — Hintergründe
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60050-helm-charts-prod.md
Helm-Charts im PROD-Cluster — Hintergründe
Begründungen zu argocd/apps/prod/*. Vieles gilt wie im TECH-Cluster und steht in 60040 (HPA mit
replicas: null, local-path, Squash, Root-Container, Zertifikate). Hier stehen die Besonderheiten der PROD-Kopien und der PROD-Apps.
Die Datenmigration von TECH nach PROD steht in 60030.
Regeln für alle PROD-Kopien
- Nie mit leeren Volumes starten. Die PROD-Kopien (Nextcloud, Immich, Paperless-ngx, Wiki.js, Xibo) sind am 2026-09-19 aus TECH
übernommen worden (migrations/README). Ein Start mit leerem Volume legt eine neue
Datenbank, neue Konten und neue Secrets an. Beim Umschalten (Teil B der Migration) steht die App während der Endkopie auf0, weil der
Kopier-Job das Zielvolume leert, danach auf1. Die Postgres-/MySQL-Deployments haben einen eigenen Schalter (replicas: 0= gestoppt, für
Umzug oder Wartung). - Release-Name = Ordnername. Secrets, PVCs und Deployments heißen in PROD wie in TECH, damit namensgebundene SealedSecrets passen
(60030). - SealedSecrets sind mit dem PROD-Schlüssel versiegelt, nicht mit dem TECH-Schlüssel (
scripts/reseal-for-prod.sh, siehe
60030). - Keine Node-Vorgabe. TECH pinnt
local-path-Apps aufhomeserver, in PROD gibt es nur dieprod-vm. - NetworkPolicy
default-ingressje App-Namespace (templates/networkpolicy.yaml, SchalternetworkPolicy.enabled). PROD hatte bis zum 2026-10-17 keine einzige Policy, ein kompromittierter Pod
erreichte jeden anderen Pod. Die Policy erlaubt Ingress nur aus dem eigenen Namespace, auskube-system(Traefik) und aus den Namespaces innetworkPolicy.extraIngressNamespaces. Anders als in TECH
fehlenmonitoring(PROD hat keinen) undcloudflared: Der PROD-Tunnel ruft nur Traefik auf, nie einen App-Service direkt. In TECH war genau diese Annahme der Grund für den Tunnel-Ausfall vom
13.08.2026 (d0030). Wer einen Pod hinzufügt, der einen anderen Namespace direkt aufruft (wie
wiki-docs-sync→wikijs), trägt dessen Namespace im Ziel-Chart unterextraIngressNamespacesein, sonst kommt der Aufruf ohne Fehlermeldung nicht an (Timeout). Nach jeder Änderung beide Wege testen:
den internen Host (*.prod.homeserver) und den öffentlichen über den Tunnel (*.pke-lab.de). Ohne Policy bleiben bewusstkube-system,cert-manager(der API-Server ruft den Webhook auf),
sealed-secrets,cloudflaredund die beiden NFS-Provisioner. - Externe Hosts laufen über den eigenen PROD-Tunnel (
homeserver-prod, 60040). Bei der PROD-Kopie von
demo-appfieldemo-prod.pke-lab.devorerst weg, weil cloudflared*.pke-lab.deauf den Traefik in TECH routet und PROD (noch) nicht kannte. - PROD-Apps haben kein zentrales SSO, weder Authentik-Middleware noch -Outpost (beides im Oktober 2026 entfernt). Es schützt nur die eigene Anmeldung der App.
Nextcloud
- Version nicht ungeprüft hochziehen. Tatsächlich auf der PVC installiert ist
34.0.2.1(geprüft am 2026-08-17 mit
require version.php; implode(".", $OC_Version)gegen die echtehtml-PVC). Ein Tag-Wechsel löst beim nächsten Pod-Start Nextclouds
Upgrade-Pfad aus, und der ist auf diesem NAS aktuell fatal. Rollback 2026-08-30: Renovate-PR #201 hob den Tag automatisiert auf
34.0.3-apachean, der Pod ging in den endlosenCrashLoopBackOff(siehe unten), zurückgesetzt auf34.0.2-apache. Das Image ist in
renovate.jsonpausiert. Bis ein sicherer Upgrade-Weg (z. B. Primärspeicher auf S3/MinIO, 300b0)
existiert, wird der Tag nur manuell und vorsichtig angehoben. - Warum das Upgrade scheitert (
all_squash): Der offizielle Entrypoint wählt seinersync-Optionen für den App-Code-Sync anhand vonid -u. Als
root nutzt er-rlDog --chown www-data:www-dataund versucht Owner/Group auf jeder einzelnen der tausenden App-Dateien zu setzen, sobald
version.phpauf der PVC von der Image-Version abweicht. Unterall_squashschlägt jederchownmit „Operation not permitted“ fehl,rsyncendet mit
Exit 23, der Container crasht, bei jedem Neustart erneut (empirisch reproduziert mit dem Tag-Bump auf 34.0.3, Troubleshooting in 300b0). Als
Nicht-root wählt der Entrypoint diechown-freie Variante (-rlD). Das wurde geprüft und verworfen: Das Image ist nicht für beliebige
Nicht-root-UIDs gebaut, z. B. ist/usr/local/etc/php/conf.d/nur für root beschreibbar, dort schreibt der Entrypoint u. a. die Redis-Session-Config
hinein („Permission denied“ schon vor dem App-Sync, per Testpod verifiziert). Root beizubehalten ist deshalb die einzig praktikable Option. - Das Apache-Image läuft als root (kein
USER, der Apache-Master-Prozess braucht Port 80), analog zu Vaultwarden ohnerunAsNonRoot. Ein früherer
Kommentar nahm an, dernas-Export sei mitno_root_squashfreigegeben, das ist seit dem Umstieg aufall_squashüberholt. - Mehrere App-Pods sind sicher, obwohl
html/dataReadWriteOnce-PVCs sind: Nextcloud nutzt ein eigenes Redis (perREDIS_HOSTverdrahtet) für
verteiltes Datei-Locking. Solange der Storage geteilt und das Locking extern ist, unterstützt die Architektur mehrere Pods. Wegen RWO/NFS zusätzlich
podAffinity, damit alle Replicas auf demselben Node laufen (die Affinity steht fest im Deployment-Template, kein konfigurierbarer Wert mehr). Das Redis
hat keine PVC: Locks und Transactional-Cache sind bei einem Neustart unkritisch und werden neu aufgebaut. trustedDomainsenthält den internen Host (*.homeserver, Traefik) und den externen (Cloudflare). Ohne beide weist Nextcloud Requests mit
„Access through untrusted domain“ ab. Dieoverwrite*-Einstellungen (overwritehost,overwriteprotocol,overwrite.cli.url) erzwingen den öffentlichen Host für alle
generierten URLs (v. a. Freigabe-Links), unabhängig davon, über welchen Host man zugreift. Gesetzt wird das peroccaus dem PostSync-Reparatur-Job. In PROD ist der Job aus:config.phpkommt
aus TECH und ist schon korrekt, auf einem leeren Volume würde er scheitern.- Postgres: Major-Upgrade 16 → 18 am 2026-08-30 (Dump/Restore, 300b0).
PGDATAin
postgres-deployment.yamlzeigt seitdem aufpgdata_pg18, der altepgdata-Ordner liegt als Rollback-Fallback auf derselben PVC und kann nach
ein paar Tagen störungsfreiem Betrieb aufgeräumt werden. Die DB liegt auflocal-path, Files und Blobs bleiben aufnas.
Immich
- Postgres ist das offizielle
immich-app/postgres-Image mit VectorChord: Das Standard-Postgres-Image reicht nicht, weil die Vektor-Ähnlichkeitssuche
eine Extension braucht, die Immich selbst mitliefert. Major-Upgrade 14 → 16 am 2026-08-30 (Dump/Restore, 300c0):
Es gibt keinen exaktenpgvectors0.2.0-Tag für Postgres 16 (GHCR-Tag-Liste geprüft), der nächste Treffer derselbenvectorchord0.4.3-Familie ist
pgvectors0.2.1(Patch-Bump, innerhalb des laut Immich-Doku unterstützten Bereichs VectorChord>=0.3,<2.0).PGDATAzeigt aufpgdata_fixed_pg16, der
altepgdata_fixed-Ordner ist Rollback-Fallback und kann nach ein paar störungsfreien Tagen aufgeräumt werden. - Server: Mehr Pods helfen gegen Abstürze durch viele gleichzeitige Uploads (mehr parallele Job-Verarbeitung), lösen aber nicht das Problem, dass ein
einzelnes sehr großes Foto oder Video mehr RAM braucht, alsresources.limitserlaubt: dafürlimits.memoryanheben. Die Pods laufen perpodAffinity
immer auf demselben Node wie die vorhandenen Server-Pods, weil dielibrary-PVCReadWriteOnceist. - Machine-Learning (Gesichtserkennung, CLIP-Suche) ist reine CPU-Inferenz, kein GPU-Passthrough.
maxReplicasist bewusst niedriger als beim Server,
jede Inferenz-Instanz belegt bis zu 4 CPU-Kerne und 4 Gi RAM. Co-Location perpodAffinitywegen desRWO-Model-Caches. - Der Redis/Valkey-Speicher (Job-Queue) hat keine PVC: Jobs werden bei einem Neustart aus der Postgres-Datenbank neu eingeplant. Die Empfehlung der Immich-Doku
für Datenintegrität ist gesetzt. Der Postgres-Backup-CronJob liefert zusätzlich zum Datei-Backup (restic aufimmich-nas) einen transaktionskonsistenten, einzeln
rückspielbaren Dump (40080). - Der Storage
immich-nasist mitno_root_squashexportiert, das Image läuft ohne erzwungenesrunAsNonRoot(analog zu Nextcloud). - Externe Bibliothek (optional, standardmäßig aus): direkter, read-only NFS-Mount für vorhandene Fotoordner (z. B. ein Massen-Export aus OneDrive), die nicht
über die Upload-API laufen, sondern per Immichs „External Library“ eingelesen werden. Die Dateien bleiben als normale Ordnerstruktur auf dem NAS, ohne
Duplikat in derlibrary-PVC. Der Unterordner auf dem NAS muss vorher manuell angelegt werden (300c0, „Externe Bibliothek“).
Wiki.js und wiki-docs-sync
- Wiki.js speichert Seiten und Assets vollständig in PostgreSQL, der App-Pod braucht kein PVC und keine NodeAffinity (Postgres schon). Postgres-Major-Upgrade
16 → 18 am 2026-08-30,PGDATA=pgdata_fixed_pg18, der altepgdata_fixed-Ordner ist Rollback-Fallback (aufräumbar nach einigen störungsfreien Tagen).
Das Postgres-Passwort ist ein Wert, den Postgres (POSTGRES_PASSWORD) und Wiki.js (DB_PASS) gemeinsam lesen. maxReplicasist auf 1 gedeckelt. Die Seiten liegen zwar vollständig in PostgreSQL, aber Wiki.js cached den API-Enable-Status und die Key-Validierung offenbar
pro Pod-Instanz ohne Sync zwischen Replicas (ohne Redis o. Ä.). Mehrere gleichzeitig aktive Pods führten zu inkonsistenten „API Key invalid“/„API disabled“-Fehlern
beim wiki-docs-sync. Das Wiki selbst stoppt man mitwikijs.autoscaling.enabled=falsepluswikijs.replicaCount=0.- wiki-docs-sync: Aufbau und Betrieb stehen in wiki-sync. Begründungen zum Chart:
- Der Code liegt im Repo capulus-wiki-sync und läuft als eigenes Image; das Chart enthält kein Skript mehr. Früher steckte
sync.pyin einem ConfigMap auf dem Standard-Imagepython, jede Skriptänderung war ein Chart-Commit und die Logik war nicht testbar. - Der CronJob läuft alle 15 Minuten. Der Sync lädt das Docs-Repo als Tarball: ein GitHub-API-Aufruf pro Lauf, egal wie viele Ordner das Repo hat. Das alte Contents-Listing brauchte einen Aufruf pro Ordner und lag damit schon am Limit für anonyme Anfragen (60/h). Der PAT (Secret
github-api-token,scripts/seal-github-token.sh) ist deshalb nur noch Komfort und für private Repos nötig; er kommt aus einem vorhandenen Secret, das der Chart nicht anlegt. wikijs.urlist der interne ClusterIP-Service, nicht die öffentliche Cloudflare-Tunnel-URL: Cloudflares Bot-Schutz blockt Requests vonurllib(403, „error code 1010“), und der Sync-Job läuft ohnehin im selben Cluster wie Wiki.js.localesteht separat vompathPrefix: Wiki.js reserviert zweistellige Pfad-Segmente (z. B.en) für das Locale, es wird nicht Teil despathPrefix, sondern von Wiki.js automatisch vor den Pfad gehängt.- Der Sync prüft die
responseResultjeder Mutation. Früher blieb ein abgelehntescreateoderupdatestill, weil nur GraphQL-Fehler ausgewertet wurden. - Ein Lauf schreibt nur geänderte Seiten. Sonst entstünde bei jedem Lauf eine neue Wiki.js-Version jeder Seite.
dryRunist beim Einführen an, weil der Sync alles unter dem Präfix löscht, was keine Quelle hat.- Der Wiki.js-API-Token liegt als SealedSecret
wiki-docs-sync-wikijs-tokenim Chart-Template (Wiki.js: Administration → Utilities → API Access). Die Templates lesen keinensecrets:-Block aus den Values. - Die frühere NetworkPolicy-Ausnahme wiki-docs-sync → wikijs (
argocd_network_policy_extra_ingress) gibt es nicht mehr: Beide Apps laufen in PROD, und dort gibt es keine Standard-Policy (40080, d0030).
- Der Code liegt im Repo capulus-wiki-sync und läuft als eigenes Image; das Chart enthält kein Skript mehr. Früher steckte
Xibo (xibosignage)
- MySQL ist ein eigenes Deployment mit dem offiziellen Image, kein Bitnami-Subchart (wie bei Wiki.js und Immich), mit Persistenz auf
nas. Major-Upgrade 8.4 → 26.7
am 2026-08-30 (Dump/Restore, 300e0): DermountPathzeigt seitdem persubPathaufmysql-data-v26, die alten
8.4-Daten liegen als Rollback-Fallback an der PVC-Wurzel und können nach einigen störungsfreien Tagen aufgeräumt werden. Das DB-Passwort ist ein Wert, den
MySQL und Xibo CMS gemeinsam lesen. - CMS-Container läuft mit Default-User (root): Das offizielle
xibo-cms-Image braucht beim ersten Start root.entrypoint.shschreibt/root/.my.cnf, konfiguriert
Apache/PHP/cron unter/etcund schreibtweb/settings.phpim Container-eigenen Rootfs. Mit erzwungenemrunAsUser: 1000schlagen alle Schritte mit
„Permission denied“ fehl (CrashLoopBackOff). Nur die Datenbank bekommtrunAsUser/runAsGroup. - Zusatzdienste, die die CMS-Oberfläche erwartet, auch wenn sie hier wenig nutzen: XMR (Xibo Message Relay, ZeroMQ-Broker zwischen CMS und Playern) ist für den
Chromium-Kiosk-Ansatz (kein echter Xibo-Player) aktuell ungenutzt, aber Teil der offiziellen CMS-Referenzarchitektur. Memcached ist der Objekt-/Session-Cache
(CMS_USE_MEMCACHED/MEMCACHED_HOST,-m 15= 15 MiB wie im offiziellendocker-compose.yml). QuickChart rendert Chart-Widgets serverseitig als PNG (optional). - Der eingebaute Cron des CMS-Containers ist aktiviert: Er erledigt periodische Wartungs-Tasks (Layout-Status, Thumbnails, Stats-Aggregation, Player-Actions), ohne ihn bleiben
Displays und Layouts nach dem ersten Sync nicht aktuell. Das Upload-Limit ist hoch gesetzt, damit große Fotos vom Handy oder NAS-Sync nicht daran scheitern. Weitere
Variablen:config.env.templateim Upstream-Repoxibosignage/xibo-docker. custom,backup,userscriptsundca-certs(aus dem offiziellendocker-compose.yml) teilen sich eine kleine PVC mit unterschiedlichensubPaths (spart drei winzige PVCs).- Zwei verschiedene Ordner nicht verwechseln: Xibo verwaltet seine Medien-Bibliothek (interne Dateinamen und Hashes) exklusiv selbst. Das ist nicht der Ordner, in den
n8n/OnlineSync Rohdateien legt (xibosignage-inbox/-displayinargocd/apps/tech/n8n, 300e0). - Der externe Host läuft ohne ForwardAuth-SSO: Nur das CMS-Login schützt ihn, analog zum früheren n8n-Setup. Der n8n-Playlist-Sync
braucht per NetworkPolicy eine Ingress-Ausnahme aufcms-web. Die Ausnahme gilt nur in TECH, in PROD gibt es keine Standard-Policy, sie hätte das CMS sonst auf einen
nicht vorhandenenn8n-Namespace isoliert (40080).
Paperless-ngx
- Paperless-ngx wurde am 2026-09-19 von TECH kopiert. Der v3-Sprung ging von
2.20.15(Zwischenschritt, siehegit log) aus: Die Konfiguration war schon sauber
für v3 (PAPERLESS_SECRET_KEYundPAPERLESS_DBENGINEgesetzt, keine deprecated Env-Vars, keine Verschlüsselung im Einsatz), der Such-Index baut sich beim ersten
Start automatisch neu auf (Whoosh → tantivy).PAPERLESS_URL(öffentliche Adresse hinter dem Reverse-Proxy) setztCSRF_TRUSTED_ORIGINSundALLOWED_HOSTS. Ohne sie scheitert das Login
mit „CSRF verification failed / Origin checking failed“ (TLS endet im Traefik, Django sieht HTTP). OCR: Deutsch plus Englisch (deu+eng, weitere perdeu+eng+fra), ein
Worker/Thread reicht für den Heimbetrieb. DerSECRET_KEYgehört in ein SealedSecret, ein fester Platzhalter ist nur vorläufig und nach dem Deploy sofort zu ersetzen.
Sonstiges
- demo-app (ENTW, PROD): Der anzuzeigende Text steckt in der Environment-Variable
MESSAGE, die man live mitkubectl set env …überschreibt. Kubernetes ersetzt$(MESSAGE)durch den
Wert,http-echogibt danach exakt diesen Text als Body aus. - cert-manager (PROD): Zertifikat und Issuer siehe 60040.
- PROD-Namespaces müssen in
argocd/bootstrap-prod/appproject.yamlstehen, sonst scheitert der Sync mit
application destination … is not permitted in project 'prod'(b0020).