App-Umzug mit Daten nach PROD
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/komponenten/bootstrap-prod-migrations.md
App-Umzug mit Daten nach PROD
Runbook und Vorlage fuer den Umzug einer App samt Daten von TECH nach PROD. Stand 21.09.2026: die
Apps paperless-ngx, wikijs, nextcloud, immich und xibosignage sind umgezogen, ihre
TECH-Ordner sind entfernt. Die Kopier-Jobs bleiben als Vorlage fuer weitere Umzuege erhalten;
Vaultwarden, Zammad und n8n bleiben bewusst in TECH
(Planung).
Manuell anzuwendende Hilfsmanifeste, nicht von ArgoCD gelesen (weder das
Manifest- noch das Charts-Set schauen in diesen Ordner).
Grundsatz: Kopie, waehrend TECH weiterlaeuft. TECH-Daten werden nur
gelesen, das alte NFS-Verzeichnis (StorageClass nas, reclaimPolicy: Retain)
bleibt unangetastet und ist der Rueckfall. Nie TECH und PROD gleichzeitig auf
dieselben Daten schreiben lassen.
Weitere Apps
Je App ein eigener Kopier-Job in diesem Ordner, gleicher Ablauf (unten):
| Job | App | Besonderheit |
|---|---|---|
paperless-ngx-data-copy-job.yaml |
paperless-ngx | 4 Volumes |
wikijs-postgres-copy-job.yaml |
wikijs | Postgres-Datenverzeichnis, eigener uid/Modus 0700 |
nextcloud-data-copy-job.yaml |
nextcloud | html- und data-Volume |
immich-data-sync-job.yaml |
immich | rsync grosser Foto-Bestaende, Postgres-Schalter |
xibosignage-data-copy-job.yaml |
xibosignage | CMS-Daten, MySQL-Schalter |
Ablauf: Push 1 = TECH und PROD auf replicaCount: 0, Endkopie, Push 2 = PROD auf 1 plus Hosts in
dnsmasq_prod_vm_hosts.
Ablauf (Vorlage fuer nas-Apps)
Alte Daten: 192.168.178.97:/volume1/k8s-storage/<app>-<pvc>-<uid>
(kubectl get pv <pv> -o jsonpath='{.spec.nfs.path}').
A. Vorbereitung (TECH laeuft unveraendert weiter)
- Committen/pushen, dann
kubectl apply -f argocd/bootstrap-prod/appproject.yaml
und beide ApplicationSets refreshen. Es entstehtprod-<app>mit
replicaCount: 0(das PVC wird in PROD angelegt, kein Pod). - Pruefen (PROD):
kubectl -n <app> get pvc. - Probekopie (TECH laeuft, die DB kann dabei inkonsistent sein, es geht nur
um den Test des Kopierwegs): Job anwenden, Logs lesen, Job loeschen. - Generalprobe:
replicaCount: 1inargocd/apps/prod/<app>/values.yaml
pushen. PROD- laeuft auf der Probekopie, TECH und DNS bleiben
unveraendert (kein Nutzer merkt etwas). Testen ueber--resolve:
curl -skI --resolve <app>.prod.homeserver:443:192.168.178.99 https://<app>.prod.homeserver
(muss200liefern). Danach vor der Endkopie wiederreplicaCount: 0pushen.
B. Umschalten (kurze Pause fuer die Nutzer)
- TECH- stoppen per Git:
replicaCount: 0in
argocd/apps/tech/<app>/values.yaml, pushen (einkubectl scale
wuerde von selfHeal zurueckgesetzt). Warten bis der Pod weg ist. - Endkopie (PROD- muss dabei auf 0 stehen): Job erneut anwenden (leert das Ziel und kopiert neu). In den
Logs muessen die erwarteten Dateien stehen (z. B. die SQLite-Datenbank); danach Job loeschen. - PROD starten:
replicaCount: 1inargocd/apps/prod/<app>/values.yaml,
pushen. Test wie in Schritt 4:
curl -skI --resolve <app>.prod.homeserver:443:192.168.178.99 https://<app>.prod.homeserver
muss200liefern. - DNS intern:
<app>.prod.homeserverin
dnsmasq_prod_vm_hosts(capulus-ansible/group_vars/all.yml),make dnsmasq. - Oeffentlich (nur der eine Host der App):
cloudflared tunnel route dns homeserver-prod <oeffentlicher-host>. NIE einen anderen Host als den der
gerade umgezogenen App eintragen.
C. Rueckweg
DNS-Eintraege (Schritte 9 und 8) zuruecknehmen (Cloudflare-Dashboard bzw.
dnsmasq_prod_vm_hosts + make dnsmasq), in TECH replicaCount: 1. Aenderungen,
die seit dem Umschalten in PROD entstanden sind, fehlen dann in TECH.
D. Aufraeumen (erst nach einigen Tagen Betrieb)
TECH-Ordner argocd/apps/tech/<app>/ entfernen. Die alten PVs bleiben
wegen Retain erhalten; das NAS-Verzeichnis erst spaeter von Hand loeschen.
Fehlersuche
kubectl -n <app> get job,pods,pvc
kubectl -n <app> logs job/<app>-data-copy # bzw. wikijs-postgres-copy, immich-data-sync, …
kubectl get pv <pv> -o jsonpath='{.spec.nfs.path}' # alter NFS-Pfad (TECH)
| Symptom | Ursache | Lösung |
|---|---|---|
Job bleibt Pending/ContainerCreating |
NFS-Mount nicht möglich (NAS 192.168.178.97 nicht erreichbar, Pfad falsch, Export nicht freigegeben) |
kubectl -n <app> describe pod, Pfad mit kubectl get pv … -o jsonpath neu bestimmen, NAS-Speicher |
Job Failed, Log: ls: /old/…: No such file |
falscher Quellpfad (PV-Name geändert) | Pfad im Job an das PV anpassen |
Permission denied beim Kopieren |
falscher Benutzer oder falsche Gruppe im Job (runAsUser, fsGroup) |
Werte an die App anpassen (zum Beispiel wikijs: Gruppe 10, Postgres-Verzeichnis Modus 0700) |
Zielvolume Pending |
PVC in PROD noch nicht angelegt, weil prod-<app> fehlt |
Schritt A1 ausführen, kubectl -n <app> get pvc |
| App in PROD startet nicht nach der Kopie (Datenbank-Fehler) | Datenbank war beim Kopieren in Betrieb (inkonsistent) | Endkopie mit gestoppter TECH-App (Schritt B5) wiederholen, Job leert das Ziel zuerst |
| Daten fehlen in PROD | Job lief gegen laufende PROD-App (Ziel muss auf 0 stehen) | PROD auf replicaCount: 0, Job erneut |
| Beide Apps schreiben in dieselben Daten | TECH nicht gestoppt | Absicht: TECH per Git auf replicaCount: 0 (nicht per kubectl scale, selfHeal setzt zurück) |
| Rückweg nötig | Probleme nach dem Umschalten | Abschnitt C (DNS zurück, TECH-replicaCount: 1), Änderungen seit dem Umschalten fehlen in TECH |
| Job lässt sich nicht erneut anwenden | ttlSecondsAfterFinished: 3600 hat den alten Job noch nicht gelöscht |
kubectl -n <app> delete job <name> und erneut anwenden |
Weiter: PROD im TECH-Hub: Fehlersuche, Planung Multi-Cluster. Allgemeine Fehlersuche: zentrale Fehlersuche.