Betrieb & Fehlerbehebung

Day-2-Betrieb: Diagnose, Lizenz-Lebenszyklus, Backups, Netzwerk-Isolation und was zu tun ist, wenn etwas klemmt.

Diagnose mit hoppla:doctor

hoppla:doctor ist dein erster Griff bei jedem Problem -- es prüft DB/TimescaleDB, Redis, Queues, Scheduler, SMTP, RLS und die Lizenz und zeigt genau, welche Schicht versagt. Es exit-codet bei Fehler ungleich null, ist also script-sicher.

# vollständige Diagnose
kubectl -n hoppla exec deploy/hoppla-api -c api -- php artisan hoppla:doctor

# Diagnose + echten Test-Versand der Mail-Zustellung
kubectl -n hoppla exec deploy/hoppla-api -c api -- \
  php artisan hoppla:doctor [email protected]

--send-test läuft im API-Pod. Denk daran: Echte Benachrichtigungen verschicken die Worker-Pods -- wenn der Test durchgeht, echte Alarme aber nicht ankommen, hast du wahrscheinlich nach einer SMTP-Änderung nur die API neu gerollt statt aller Deployments (siehe Installation → E-Mail).

Lizenz-Lebenszyklus

Deine Instanz wird über eine signierte Lizenzdatei gesteuert und phont nie nach Hause.

• Status sehen: im Dashboard-Banner und über php artisan license:verify (exit-codet ungleich null, wenn das Update-Fenster überschritten ist) bzw. php artisan license:inspect (zeigt u. a. updates_until).
• Verlängern = eine neue Lizenzdatei. Ersetze das hoppla-license-Secret -- die Instanz nimmt beim nächsten Check (≤ 60 s) wieder auf. Kein Neustart, keine Neuinstallation, kein Datenverlust.
• Nach Ablauf gibt es ein Kulanzfenster, dann wird die Instanz read-only: Checks und Alerting pausieren, aber Dashboards, Historie und Status Pages bleiben oben. Es gehen keine Daten verloren -- sobald du eine gültige Lizenz einspielst, läuft das Monitoring nahtlos weiter.

kubectl -n hoppla create secret generic hoppla-license \
  --from-file=hoppla.license=neue-lizenz.txt --dry-run=client -o yaml \
  | kubectl -n hoppla apply -f -

Mehr zu Update-Fenstern und der Reihenfolge „verlängern, dann upgraden" steht unter Upgrades & Wartung → Lizenz- und Update-Fenster.

Backups

Alles, was zählt, lebt in PostgreSQL und in den Secrets, die du angelegt hast. Sichere also genau diese beiden Dinge.

# Datenbank-Dump nach deinem Zeitplan
kubectl -n hoppla exec statefulset/hoppla-postgresql -- \
  pg_dump -U hoppla hoppla > backup-$(date +%F).sql

• Die Daten liegen auf dem PVC hinter dem Postgres-StatefulSet -- behandle das PVC + deine pg_dumps als das, was es zu schützen gilt.
• Sichere auch deine Secrets (hoppla-secrets, hoppla-license) -- ohne APP_KEY sind verschlüsselte Spalten nicht mehr lesbar.
• Teste Restores regelmäßig. Ein ungetestetes Backup ist kein Backup.
• Redis braucht kein Backup: Es hält nur Queues und Cache, keine dauerhaften Daten. Worst Case nach einem harten Neustart: ein paar Checks laufen doppelt.

Das Chart kann optional einen pg_dump-CronJob mitlaufen lassen (backups.enabled: true, mit backups.schedule und backups.retentionDays).

Netzwerk-Isolation

Netzwerk-Isolation funktioniert auf jedem CNI:

networkPolicy:
  enabled: true
  backend: standard   # der cilium-Backend ist verfügbar, wenn du Cilium fährst

Bei aktivierter Policy bekommen PostgreSQL und Redis eigene Regeln, die den Zugriff auf die App-Pods beschränken. Details unter Konfiguration → Network Policies.

Häufige Probleme

Symptom	Wahrscheinliche Ursache & Fix
App nur per port-forward erreichbar	ingress.enabled ist standardmäßig false -- Ingress-Override anlegen (Installation)
Test-Mail geht durch, echte Alarme nicht	nach SMTP-Änderung nur die API gerollt -- kubectl -n hoppla rollout restart deploy (alle Deployments)
Migration scheitert auf gemanagter DB	RDS/Cloud SQL haben kein TimescaleDB -- siehe Skalierung & Betreiber
Zertifikatsfehler bei *.status/*.portal	zweistufige Wildcards brauchen DNS-01, nicht HTTP-01 (Konfiguration)
Eigene Kundendomain bekommt CF Error 1014	das CNAME-Ziel ist auf Cloudflare geproxyt -- grau lassen (Konfiguration)
hoppla:doctor warnt: Probe-Labels identisch	Single-Cluster-Setup -- erwartet; echtes Multi-Region siehe Skalierung
Dashboard-Banner: Lizenz read-only	Update-Fenster oder Lizenz abgelaufen -- neue Lizenzdatei einspielen (siehe oben)
Pod ziehen schlägt fehl (ImagePullBackOff)	hoppla-registry-Secret fehlt oder Token abgelaufen -- siehe Konfiguration → Secrets

Bei jedem Problem zuerst:

kubectl -n hoppla exec deploy/hoppla-api -c api -- php artisan hoppla:doctor
kubectl -n hoppla get pods
kubectl -n hoppla logs deploy/hoppla-api

Support

E-Mail-Support mit deiner Kunden-ID (aus dem Welcome-Pack). Häng bitte immer die vollständige Ausgabe von php artisan hoppla:doctor an -- sie beantwortet die meisten Umgebungsfragen schon vorab und erspart eine Rückfragerunde.