Kubernetes-Deployment¶

Kamerplanter wird über ein einzelnes Helm-Chart deployt, das alle Komponenten enthält: Backend, Frontend, ArangoDB und Valkey. Die Container-Images und das Helm-Chart liegen in der GitHub Container Registry (ghcr.io).

Voraussetzungen¶

Überblick: Was wird deployt?¶

flowchart TB
    subgraph "Kubernetes Cluster"
        direction TB
        ING["Ingress<br/>(Traefik / nginx)"]

        subgraph "Kamerplanter Namespace"
            FE["Frontend<br/>(Deployment, 2 Replicas)"]
            BE["Backend<br/>(Deployment, 2 Replicas)"]
            DB["ArangoDB<br/>(StatefulSet, 1 Replica)"]
            VK["Valkey<br/>(Deployment, 1 Replica)"]
        end
    end

    ING -->|"/ und /api/*"| FE
    BE --> DB
    BE --> VK
    FE -->|"proxy /api"| BE

    style ING fill:#FF9800,color:#fff
    style FE fill:#66BB6A,color:#fff
    style BE fill:#43A047,color:#fff
    style DB fill:#2E7D32,color:#fff
    style VK fill:#1B5E20,color:#fff

Installation¶

1. Helm-Repository hinzufügen¶

Das Kamerplanter Helm-Chart liegt als OCI-Artefakt in der GitHub Container Registry:

# OCI-Registries benötigen kein helm repo add —
# der Pull erfolgt direkt über die OCI-URL
helm pull oci://ghcr.io/nolte/charts/kamerplanter --version 0.2.0

echo $GITHUB_TOKEN | helm registry login ghcr.io --username $GITHUB_USER --password-stdin

2. Pflicht-Secrets anlegen¶

kubectl create namespace kamerplanter

kubectl create secret generic kamerplanter-secrets \
  --namespace kamerplanter \
  --from-literal=ARANGODB_PASSWORD="dein-sicheres-passwort" \
  --from-literal=ARANGO_ROOT_PASSWORD="dein-sicheres-passwort" \
  --from-literal=JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  --from-literal=FERNET_KEY="$(python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')" \
  --from-literal=ERASURE_TOMBSTONE_SALT="$(openssl rand -hex 32)" \
  --from-literal=LOG_PSEUDONYM_SALT="$(openssl rand -hex 32)"

Schaltest du TimescaleDB ein (controllers.timescaledb.enabled: true), braucht das Secret zusätzlich TIMESCALEDB_PASSWORD — siehe TimescaleDB.

Datenbank-Zugänge¶

Die Anwendung verbindet sich nicht als root mit ArangoDB, sondern mit dem Konto kamerplanter (database.arangodb.appUsername). Ein Hilfscontainer app-user im ArangoDB-Pod legt es bei jedem Start an bzw. aktualisiert es: Passwort aus ARANGODB_PASSWORD, Lese- und Schreibrecht nur auf der Anwendungsdatenbank, kein Zugriff auf _system. Der ArangoDB-Container selbst erhält aus dem Secret nur ARANGO_ROOT_PASSWORD.

• ARANGODB_PASSWORD ist das Passwort des Anwendungskontos. Wähle einen eigenen Wert, nicht das Root-Passwort.
• ARANGO_ROOT_PASSWORD braucht nur der ArangoDB-Pod. Lege es in ein eigenes Secret, dann sieht das Backend das Root-Passwort nicht mehr (es liest kamerplanter-secrets vollständig per envFrom):

kubectl create secret generic kamerplanter-arangodb-root \
  --namespace kamerplanter \
  --from-literal=ARANGO_ROOT_PASSWORD="$(openssl rand -hex 32)"

database:
  arangodb:
    rootPasswordSecret: kamerplanter-arangodb-root

Vollständige Übersicht aller Pflicht-Secrets je aktivierter Funktion (z. B. INTERNAL_SERVICE_TOKEN sobald der KI-Assistent oder die Bilderkennung aktiv sind): Konfigurationsmatrix — Pflicht-Secrets.

3. Values-Datei erstellen¶

Erstelle eine values-production.yaml mit deinen Anpassungen:

controllers:
  backend:
    replicas: 2     # (1)!
    containers:
      main:
        envFrom:
          - secret: kamerplanter-secrets    # (2)!
        env:
          ARANGODB_HOST: kamerplanter-arangodb
          ARANGODB_PORT: "8529"
          ARANGODB_DATABASE: kamerplanter
          REDIS_URL: redis://kamerplanter-valkey:6379/0
          CORS_ORIGINS: '["https://pflanzen.example.com"]'
          DEBUG: "false"
          KAMERPLANTER_MODE: full    # (3)!

  frontend:
    replicas: 2

  arangodb:
    statefulset:
      volumeClaimTemplates:
        - name: data
          accessMode: ReadWriteOnce
          size: 10Gi    # (5)!
          advancedMounts:    # (4)!
            main:
              - path: /var/lib/arangodb3

# Anhänge in S3 — Pflicht bei mehr als einer Backend-Replica
storage:
  backend: s3
  s3:
    endpointUrl: https://s3.eu-central-1.amazonaws.com
    region: eu-central-1
    bucket: kamerplanter-prod
    credentialsRef:
      secretName: storage-s3-credentials

ingress:
  main:
    enabled: true
    hosts:
      - host: pflanzen.example.com    # (6)!
        paths:
          - path: /              # auch /api: das Frontend-nginx leitet es ans Backend weiter
            pathType: Prefix
            service:
              identifier: frontend

1. Zwei Replicas für Rolling Updates ohne Downtime. Nur mit S3 (storage.backend: s3, siehe unten) oder einem ReadWriteMany-Volume: Auf dem Standard-Volume ReadWriteOnce verweigert das Chart mehr als eine Backend-Replica, weil ein zweiter Pod auf einem anderen Node nie startet (Storage-Konfiguration).
2. Zieht ARANGODB_PASSWORD, JWT_SECRET_KEY, FERNET_KEY, ERASURE_TOMBSTONE_SALT und LOG_PSEUDONYM_SALT aus dem im vorigen Schritt angelegten Secret — keine Klartext-Passwörter in values.yaml.
3. light = ohne Login/Tenant-System, ein Nutzer. full (Standard im Chart) = mit JWT-Auth und Mandantenverwaltung. Details: Betriebsprofile.
4. Nur der ArangoDB-Container main mountet das Datenvolume, nicht der Hilfscontainer app-user. Das Root-Passwort und das Anwendungskonto stellt das Chart selbst ein (siehe Datenbank-Zugänge); setze hier kein envFrom und kein ARANGODB_USERNAME.
5. Passe die Größe an deinen Bedarf an. Der Chart-Default für die ArangoDB-PVC liegt bei 5Gi.
6. Dein gewünschter Hostname. Der Ingress-Controller muss darauf konfiguriert sein.

4. Helm-Chart installieren¶

helm install kamerplanter \
  oci://ghcr.io/nolte/charts/kamerplanter \
  --version 0.2.0 \
  --namespace kamerplanter \
  --create-namespace \
  --values values-production.yaml

5. Deployment prüfen¶

# Pod-Status prüfen
kubectl get pods -n kamerplanter

# Auf gesunde Pods warten
kubectl wait --for=condition=ready pod \
  --all -n kamerplanter --timeout=120s

Erwartete Ausgabe:

NAME                                      READY   STATUS    RESTARTS   AGE
kamerplanter-backend-7d8f9b6c4d-abc12     1/1     Running   0          45s
kamerplanter-backend-7d8f9b6c4d-def34     1/1     Running   0          45s
kamerplanter-frontend-5c4d8e7f3b-ghi56    1/1     Running   0          45s
kamerplanter-frontend-5c4d8e7f3b-jkl78    1/1     Running   0          45s
kamerplanter-arangodb-0                   1/1     Running   0          45s
kamerplanter-valkey-0                     1/1     Running   0          45s

Updates durchführen¶

# Auf neue Version aktualisieren
helm upgrade kamerplanter \
  oci://ghcr.io/nolte/charts/kamerplanter \
  --version 0.3.0 \
  --namespace kamerplanter \
  --values values-production.yaml

Die Backend- und Frontend-Deployments führen ein Rolling Update durch — es gibt keine Downtime, da die alten Pods erst beendet werden, wenn die neuen bereit sind.

Startdauer des Backends¶

Ein neuer Backend-Pod richtet vor dem ersten Request die Datenbank ein: Er legt fehlende Collections und Indizes an, führt die offenen Migrationen aus und spielt die Stammdaten-Seeds ein. Erst danach nimmt er Verbindungen an. Das passiert bewusst im Backend-Prozess selbst und nicht in einem eigenen Migrations-Job — ein Upgrade braucht also keinen zusätzlichen Schritt.

Auf einer leeren Datenbank dauert das rund 40 Sekunden (gemessen auf einer Workstation; unter dem Chart-Limit von 1 CPU eher länger). Mit einer langen Migration, oder wenn ein anderer Pod gerade migriert und dieser hier wartet, dauert es mehrere Minuten. Damit Kubernetes den Pod in dieser Zeit nicht neu startet, prüft zuerst ein startupProbe den Start; Liveness- und Readiness-Probe beginnen erst, wenn er erfolgreich war. Bis dahin bleibt der alte Pod im Dienst.

Was das für dich bedeutet:

• Wartet ein Pod länger als 600 Sekunden auf eine Migration, die ein anderer Pod hält, beendet er sich selbst mit MigrationBarrierTimeoutError — das Backend entscheidet über den Fehlschlag, nicht das Kubelet. Die maximale Startdauer liegt deshalb immer über dieser Wartezeit.
• Wird ein migrierender Pod abgebrochen, bleibt sein Lock bis zu 300 Sekunden stehen; danach übernimmt ein anderer Pod. Ein Neustart in dieser Zeit wartet also, statt sofort zu migrieren.
• Braucht eine Migration länger als 15 Minuten, erhöhe vor dem Upgrade failureThreshold des startupProbe (die übrigen Probe-Werte bleiben erhalten). Senke ihn nie unter 70: Ein Pod, der die vollen 600 Sekunden auf eine fremde Migration gewartet hat, braucht danach noch seinen eigenen Start (rund 40 Sekunden, unter 1 CPU länger). 10 s × 70 = 700 Sekunden lassen dafür 100 Sekunden Aufschlag; mit weniger bricht Kubernetes einen Pod ab, der rechtmäßig wartet oder gerade fertig startet.
• Beim Hochskalieren (Replicas oder Autoscaler) hilft ein neuer Pod erst nach seinem Start. Plane die Skalierung mit Minuten, nicht Sekunden.

controllers:
  backend:
    containers:
      main:
        probes:
          startup:
            spec:
              failureThreshold: 180    # 10 s × 180 = 30 Minuten

Deinstallation¶

helm uninstall kamerplanter --namespace kamerplanter

kubectl delete pvc --all -n kamerplanter

Monitoring¶

Logs prüfen¶

# Backend-Logs
kubectl logs -l app.kubernetes.io/component=backend -n kamerplanter --tail=50

# Frontend-Logs
kubectl logs -l app.kubernetes.io/component=frontend -n kamerplanter --tail=50

# ArangoDB-Logs
kubectl logs -l app.kubernetes.io/component=arangodb -n kamerplanter --tail=50

Health-Checks¶

Das Backend bietet zwei Health-Endpunkte:

# Manuell testen (über Port-Forward)
kubectl port-forward svc/kamerplanter-backend 8000:8000 -n kamerplanter
curl http://localhost:8000/api/v1/health/ready

Fehlerbehebung¶

Siehe auch¶

• Konfigurationsmatrix — Vollständige Referenz aller Pflicht-Secrets je Funktion
• Helm Charts — Detaillierte Beschreibung der Chart-Struktur und aller Konfigurationsoptionen
• ArgoCD — GitOps-basiertes Deployment mit deklarativem Secret-Management
• Docker Compose Schnellstart — Einfachere Alternative mit Docker Compose
• Docker Compose Dauerbetrieb — Docker-Compose-basierter Dauerbetrieb