Oppgradering

Denne guiden dekker oppgraderingsprosessen for Lumi installert med Helm.

Forutsetninger

• helm og kubectl installert
• Tilgang til Kubernetes-clusteret der Lumi kjører
• Kjenn gjeldende versjon: helm list -n lumi

Versjonspinning

Lumi publiserer Docker-images og Helm chart med semantisk versjonering. Chart-versjon og appVersion følger hverandre 1:1 — bump begge i samme release.

Artefakt	Anbefalt pinning
Helm chart	--version 1.2.3
API-image	api.image.tag=1.2.3
Dashboard-image	dashboard.image.tag=1.2.3
PostgreSQL subchart runtime image	postgresql.image.digest=sha256:...
Valkey subchart runtime image	valkey.image.digest=sha256:...
PostgreSQL/Valkey metrics images	postgresql.metrics.image.digest=sha256:..., valkey.metrics.image.digest=sha256:...
PostgreSQL/Valkey volume-permissions image	postgresql.volumePermissions.image.digest=sha256:..., valkey.volumePermissions.image.digest=sha256:...

Hvis api.image.tag eller dashboard.image.tag er tom (default i values.yaml), faller chart-en tilbake til Chart.AppVersion. PostgreSQL og Valkey defaulter til digest-pinnede runtime images, inkludert opt-in metrics exporter og volume-permissions images. Eksplisitt pinning i egne values-filer er fortsatt anbefalt for produksjon — da er du ikke avhengig av chart-revisjonen som ble installert.

Ikke bruk latest-tag i produksjon

latest oppdateres ved hver commit til main og er ikke egnet for produksjon. Bruk alltid eksplisitte versjonstagger.

Før oppgradering

1. Ta backup av databasen

kubectl exec -n lumi lumi-postgresql-0 -- \
  pg_dump -U lumi -d lumi > lumi-backup-$(date +%F).sql

Ekstern database

Hvis du bruker ekstern PostgreSQL (postgresql.enabled=false), bruk din vanlige backup-prosedyre (f.eks. pg_dump direkte eller managed snapshots).

2. Les endringslogg

Sjekk CHANGELOG.md i din lokale klone for breaking changes mellom din gjeldende versjon og målversjonen.

3. Forbered publishable API keys

Fra og med versjonen som innfører påkrevde allowedOrigins, avviser API-et nye pk_-nøkler uten minst én origin med HTTP 400. Eksisterende aktive pk_-nøkler uten allowedOrigins er en upgrade-blocker: preflight og API-startup feiler før ny versjon begynner å serve.

Remediering er å opprette nye pk_-nøkler med eksplisitte allowedOrigins, oppdatere widget-konfigurasjonen, og deretter revokere de gamle nøklene. Ikke bruk eksisterende rotate-endepunkt som remediation for legacy unrestricted keys: rotasjon kopierer nøkkelens eksisterende allowedOrigins.

Oppdater automatisering eller runbooks som oppretter publishable keys før oppgradering. CLI-bruk må sende én eller flere --allowed-origin <origin> når den lager pk_-nøkler. Bruk bare api.env.allowUnrestrictedPkOrigins=true / LUMI_ALLOW_UNRESTRICTED_PK_ORIGINS=true som et midlertidig, eksplisitt unntak for lokal utvikling eller lukkede/trusted deployments. Ikke la unntaket stå på i produksjon.

Helm chartet kjører en pre-upgrade Job (check-pk-origins) før API Deployment oppdateres. Jobben bruker nåværende live DB-env fra eksisterende API ConfigMap/Secret, target API-image, og target-verdi for unrestricted-origin-unntaket. Hvis oppgraderingen samtidig bytter DB host, DB_JDBC_URL, database-credentials eller Secret-navn, kjør DB-endringen i et separat steg eller kjør check-pk-origins manuelt mot target-databasen før Deployment apply.

For GitOps og helm template-flyter: kjør den rendrerte preflight-Jobben alene og vent på Complete før resten av manifestene applyes. Hvis hook-ressursene ikke brukes av verktøyet ditt, kjør tilsvarende one-off Job med samme API-image og DB-env. En startup-guard i API-et stopper fortsatt ny pod før serving hvis preflighten er hoppet over.

4. Verifiser at nåværende deployment er sunn

# Sjekk pod-status
kubectl get pods -n lumi

# Sjekk API health
kubectl exec -n lumi deploy/lumi-api -- curl -s localhost:8080/internal/isAlive
# Forventet: OK

kubectl exec -n lumi deploy/lumi-api -- curl -s localhost:8080/internal/isReady
# Forventet: OK

Oppgradering

helm upgrade lumi oci://ghcr.io/asorheim/lumi-analytics/charts/lumi \
  --namespace lumi \
  --version <ny-versjon> \
  --reuse-values

Hva skjer under oppgradering

1. Helm bytter API-pods med Recreate-strategi, slik at gamle og nye API-versjoner ikke håndterer innsendinger samtidig
2. Nye API-pods kjører Flyway-migrasjoner automatisk ved oppstart
3. Dashboard-pods oppdateres med vanlig Kubernetes rolling update

Chart-genererte ConfigMaps og Secrets inngår i pod-template checksum. Endringer i chart-verdier for DB, Valkey, OIDC client secret eller session secret trigger derfor ny API/dashboard-pod ved helm upgrade.

Eksterne Secrets

Når api.existingSecret eller dashboard.existingSecret peker på en forhåndsopprettet Kubernetes Secret, kan ikke Helm se endringer i Secret-dataene. Etter rotasjon av en slik Secret må du enten endre Secret-navnet i values eller kjøre manuell rollout, for eksempel kubectl rollout restart deploy/lumi-api deploy/lumi-dashboard -n lumi.

Ingen blandede API-versjoner

Kjør ikke blue/green, canary, flere Helm-releaser eller manuelle ekstra API-Deployments mot samme database under oppgraderinger som endrer survey-definition-semantikk. Kun én API-versjon skal kunne motta /api/v1/submission-trafikk om gangen.

Dette gjelder også origin-guard-oppgraderingen: gamle pods kan fortsatt opprette eller godta unrestricted pk_-nøkler. Ikke kjør gamle og nye API-versjoner parallelt mot samme database når du fjerner legacy unrestricted keys.

Rollback etter midlertidig unntak

Hvis du aktiverer unrestricted-origin-unntaket for å komme gjennom en oppgradering, må unntaket spores til alle legacy pk_-nøkler er erstattet og revokert. Rollback til en eldre chart/image uten remediation gjør at unrestricted keys igjen aksepteres uten startup-guard.

Oppgrader alltid én minor-versjon om gangen. Ikke hopp over versjoner.

Databasemigrasjoner

Lumi bruker Flyway for databasemigrasjoner. Migrasjoner kjøres automatisk når API-et starter — ingen manuell intervensjon er nødvendig.

Migrasjonsbaseline

Lumi v1.0 inneholder en squashet migrasjonsbaseline (V1__baseline.sql). Denne guiden gjelder oppgraderinger fra v1.0 og nyere. Oppgradering fra pre-release-versjoner støttes ikke — bruk en fresh install.

Viktige egenskaper:

• Forward-only — migrasjoner kan ikke reverseres
• Automatisk — kjøres ved oppstart, før API-et mottar trafikk
• Bakoverkompatible — nye migrasjoner er designet for å fungere med forrige app-versjon

Migreringsregler

Alle migrasjoner følger disse reglene for å sikre trygg rollback:

• Ingen DROP COLUMN eller DROP TABLE på eksisterende objekter
• Ingen ALTER COLUMN TYPE på eksisterende kolonner
• Ingen kolonneendringer (rename)
• Nye NOT NULL-kolonner må ha DEFAULT-verdi
• Kun additive endringer: nye tabeller, nye kolonner, nye indekser

Pre-release baseline-squash

Den tidligere pre-release-historikken (V1-V7) ble slått sammen før første supported release. Hvis du har kjørt en pre-release-installasjon med den gamle historikken, skal databasen ikke oppgraderes videre med v1.0-bildene. Eksporter eventuelle testdata du vil beholde, opprett databasen på nytt, og importer data via støttede API-er.

Cache (Valkey)

Valkey er et rent cache-lag uten persistent tilstand. Det er trygt å tømme Valkey under oppgradering.

Brukersesjoner

Aktive brukersesjoner er lagret i PostgreSQL-tabellen sessions og krypteres med LUMI_SESSION_SECRET. Det er trygt å tømme Valkey uten å logge ut brukere, men sletting av sessions-tabellen eller rotasjon uten gammel session secret vil kreve ny innlogging.

LUMI_WIDGET_PREVIEW (demo only — DO NOT SET ON CUSTOMER DEPLOYMENTS)

dashboard.env.lumiWidgetPreview mounts a survey widget overlay on the dashboard for demo purposes. It hardcodes a demo API key into the client bundle. CI includes a leak guard that fails if this value renders under prod defaults.

Rollback

App-kode

helm rollback lumi -n lumi

Rollback er kun trygt til forrige versjon (N-1) når den nye versjonen ikke har akseptert data som den gamle app-koden tolker annerledes. Helm ruller tilbake API- og dashboard-containere, men påvirker ikke PostgreSQL-subchartet. PVC-er (databasedata) beholdes.

Survey-definition hash

Ikke rull tilbake over versjonen som innfører order-sensitive definition_hash etter at API-et har akseptert submissions. Eldre API-kode sorterte field/order-semantikk i hashberegningen og kan derfor godta eller skrive om reorderede fields/options under samme surveyId. Ved nødvendig rollback: stopp all /api/v1/submission-trafikk først, vurder restore fra backup, og ikke start gammel API-kode mot databaser som har mottatt nye order-sensitive definitions.

Database

Databasemigrasjoner kan ikke rulles tilbake. Fordi migrasjoner er bakoverkompatible med forrige versjon, vil den gamle app-koden fungere mot det nye skjemaet.

Worst case (inkompatibel migrasjon): Restore fra backup.

# Restore fra backup
kubectl exec -i -n lumi lumi-postgresql-0 -- \
  psql -U lumi -d lumi < lumi-backup-YYYY-MM-DD.sql

Validering etter oppgradering

# 1. Sjekk pod-status
kubectl get pods -n lumi

# 2. Sjekk API health
kubectl exec -n lumi deploy/lumi-api -- curl -s localhost:8080/internal/isAlive
# Forventet: OK

# 3. Sjekk Flyway-migrasjoner i API-logg
kubectl logs -n lumi deploy/lumi-api | grep "Flyway"
# Forventet: "Database migrations completed!" og "Migrations executed: N"

# 4. Sjekk at dashboardet laster
kubectl exec -n lumi deploy/lumi-dashboard -- curl -s localhost:3000
# Forventet: HTML-respons

Docker Compose (utvikling)

For lokale utviklingsmiljøer med Docker Compose: docker compose pull && docker compose up -d.