Upgrades & Wartung

Diese Seite behandelt alles Betriebliche nach der Installation: wie du von neuen Releases erfährst, Routine-Upgrades, beschleunigte Sicherheits-Updates, Rollback und die Pflege des darunterliegenden Stacks (PostgreSQL/TimescaleDB, Redis, dein Cluster).

Kurzfassung -- Routine-Upgrade

# 0. Prüfen, ob dein Lizenz-Fenster das Release abdeckt (siehe "Lizenz- und Update-Fenster")
kubectl -n hoppla exec deploy/hoppla-api -- php artisan license:verify

# 1. IMMER zuerst sichern
kubectl -n hoppla exec statefulset/hoppla-postgresql -- pg_dump -U hoppla hoppla > backup-$(date +%F).sql

# 2. Auf eine gepinnte Version mit DEINER Werte-Datei upgraden
helm upgrade hoppla oci://ghcr.io/jkbennemann/charts/hoppla-selfhosted \
  --version <NEW_VERSION> -n hoppla -f my-values.yaml

# 3. Verifizieren
kubectl -n hoppla exec deploy/hoppla-api -- php artisan hoppla:doctor

Wie du von neuen Releases erfährst

Deine Instanz ist vollständig offline -- sie phont nie nach Hause, sie wird dir also nicht sagen, dass eine neue Version existiert. Bleib auf dem Laufenden über:

• Beobachte das hoppla-dist-Repository (GitHub → Watch → Custom → Releases). Jedes Release landet dort als Tag + eine neue Zeile in VERSIONS.md mit der Chart-Referenz und den Image-Tags.
• VERSIONS.md in hoppla-dist ist die kanonische Versionstabelle -- Neuestes oben, mit den OCI-Chart-Koordinaten für helm upgrade.
• Sicherheitshinweise gehen an den Betreiber-Kontakt deines Vertrags und werden in den hoppla-dist-Release-Notes veröffentlicht, markiert mit [SECURITY].

Empfohlener Rhythmus: ein monatliches Wartungsfenster für Routine-Upgrades, plus beschleunigte Fenster für [SECURITY]-Releases (siehe unten).

Release-Typen

Versionen folgen MAJOR.MINOR.PATCH:

Typ	Enthält	Migrationen	Aktion nötig
Patch	Bugfixes, Sicherheitsfixes, Dependency-Bumps	nur additiv, meist keine	zeitnah upgraden; nie Werte-Änderungen nötig
Minor	Neue Features, neue optionale Werte	nur additiv	Notes lesen; neue Werte sind optional mit sicheren Defaults
Major	Breaking Changes, erforderliche Werte-Änderungen, destruktive Migrationen	möglicherweise destruktiv	die Upgrade-Schritte in den Notes lesen, bevor du etwas anfasst

Regeln, die Upgrades langweilig halten:

• Versionen pinnen. Immer --version übergeben; nie auf latest verlassen.
• Eine Werte-Datei behalten (my-values.yaml) unter Versionskontrolle und immer mit -f übergeben. Verwende nicht --reuse-values -- es friert Chart-Default-Änderungen ein und erzeugt Drift, der elend zu debuggen ist.
• Ein Major nach dem anderen upgraden (1.x → 2.x → 3.x; nie 1.x → 3.x).
• Migrationen laufen automatisch -- ein Init-Container führt php artisan migrate --force aus, bevor die neue API startet; Workers erhalten SIGTERM und entleeren laufende Checks sauber (60s).

Sicherheits-Updates

[SECURITY]-Releases sind Patch-Releases und sicher sofort anwendbar:

1. Lies den Hinweis -- er nennt die betroffenen Komponenten und ob der Fix in den Anwendungs-Images, im Chart oder in beidem steckt.
2. Führe das Routine-Upgrade aus (Kurzfassung oben). In einem Security-Patch gibt es nie eine Werte-Änderung.
3. Deckt der Hinweis eine Base-Image-CVE ab (PHP, nginx, Alpine), ist der Fix schlicht das neu gebaute Image -- gleiche Prozedur.
4. Deckt der Hinweis PostgreSQL/TimescaleDB oder Redis ab und du fährst die In-Cluster-Defaults, bumpt das Release postgresql.image.tag / redis.image.tag im Chart; das StatefulSet rollt beim Upgrade. Bringst du deine eigene Datenbank mit, patchst du sie auf deiner Seite gemäß dem Hinweis.

Nach jedem Security-Upgrade: hoppla:doctor, dann Login und eine Monitor-Detailseite stichprobenartig prüfen.

Nach jedem Upgrade

kubectl -n hoppla exec deploy/hoppla-api -- php artisan hoppla:doctor   # alles OK?
kubectl -n hoppla get pods                                              # alles Running?

Dann im Dashboard: Lizenz-Banner abwesend (oder wie erwartet), Checks ticken in der Historie eines Monitors, kein Wachstum bei den Failed-Job-Zählern unter Admin → System.

Rollback

helm rollback hoppla -n hoppla            # vorherige Revision

Hat das fehlgeschlagene Upgrade neue Migrationen ausgeführt, stelle zuerst den Datenbank-Dump aus Schritt 1 wieder her, dann roll zurück. (Minor-/Patch-Migrationen sind additiv, ein einfaches helm rollback reicht also normalerweise.) Roll eine Revision zurück und verifiziere erneut; nie blind Rollbacks aneinanderreihen.

Lizenz- und Update-Fenster

Deine Lizenz trägt ein updates_until-Datum: Builds, die nach diesem Datum veröffentlicht werden, laufen read-only, bis du verlängerst (das Dashboard-Banner sagt dir genau das, und license:verify exit-codet ungleich null). Daher:

• Vergleiche vor einem Upgrade das Release-Datum in VERSIONS.md mit deinem updates_until (php artisan license:inspect zeigt es). Ist das Release neuer, verlängere zuerst -- dann upgrade.
• Verlängern = das hoppla-license-Secret ersetzen -- wird innerhalb von 60 Sekunden übernommen, kein Neustart, keine Neuinstallation, kein Datenverlust.
• Ein abgelaufenes Update-Fenster bricht nie die Version, die du bereits fährst.

Den Unterbau pflegen

PostgreSQL / TimescaleDB (In-Cluster-Default)

• Minor-PG-/TimescaleDB-Bumps kommen als Chart-Updates (der timescale/timescaledb-Tag) und rollen automatisch. Nach einem TimescaleDB-Bump sagen die Release-Notes, ob ALTER EXTENSION timescaledb UPDATE; nötig ist -- wenn ja, enthalten die Notes den exakten Schritt.
• Major-PG-Upgrades (z. B. 16 → 17) sind nie still: Sie erscheinen nur in MAJOR-Releases mit einem dokumentierten Dump → Upgrade → Restore-Pfad.
• Die Daten leben auf dem PVC hinter dem StatefulSet -- behandle das PVC + deine pg_dumps als das, was es zu schützen gilt. Teste Restores regelmäßig.

Redis (In-Cluster-Default)

Redis hält Queues und Cache, keine dauerhaften Daten. Chart-Bumps rollen das StatefulSet; laufende Jobs entleeren zuerst (Workers hören bei SIGTERM auf zu konsumieren). Worst Case nach einem harten Neustart: ein paar Checks laufen doppelt. Kein Backup nötig.

Kubernetes / Nodes

App-Pods sind zustandslos und reschedulen frei. Für Node-Wartung:

• Multi-Node: kubectl drain <node> wie üblich -- PodDisruptionBudgets halten API und Workers verfügbar.
• Single-Node: Während des Node-Reboots ist eine kurze Komplett-Auszeit zu erwarten; das Monitoring nimmt von selbst wieder auf, und das verpasste Fenster erscheint als Lücke, nicht als False-Downs (für die ausfallende Instanz selbst feuern keine Alarme).

TLS-Zertifikate

cert-manager erneuert alles automatisch. Nach einem Restore aus Backup oder einem Cluster-Wechsel prüfe erneut: kubectl -n hoppla get certificate -- alle READY.

Wenn etwas schiefgeht

1. php artisan hoppla:doctor -- es zeigt genau, welche Schicht versagt.
2. kubectl -n hoppla get pods + kubectl -n hoppla logs deploy/hoppla-api.
3. Roll zurück (siehe oben) -- die vorherigen Images bleiben pullbar, unabhängig von deinem Update-Fenster.
4. Support: E-Mail mit deiner Kunden-ID und der vollständigen hoppla:doctor-Ausgabe.

Mehr zur laufenden Diagnose und zum Lizenz-Lebenszyklus steht unter Betrieb & Fehlerbehebung.