Kubernetes-Betrieb

Nutzen Sie diese Anleitung, wenn Sie Workspace produktiv in Kubernetes betreiben möchten. Nach Abschluss läuft Workspace als Deployment hinter einem Ingress, verwendet eine externe PostgreSQL-Datenbank und speichert Konfiguration sowie Dateien auf persistentem Speicher.

Diese Seite beschreibt einen neutralen Kubernetes-Betrieb. Passen Sie StorageClass, IngressClass, TLS-Ausstellung, Secret-Verteilung und PostgreSQL-Betrieb an Ihre Plattform an.

Wann passt Kubernetes?

Kubernetes passt, wenn Ihr Betriebsteam diese Aufgaben bereits zentral löst:

• Image-Rollouts und Rollbacks,
• Ingress, TLS und öffentliche Hostnamen,
• Secret-Verteilung,
• persistente Volumes,
• Health-Checks, Logs und Monitoring,
• Datenbankbetrieb außerhalb des Workspace-Pods.

Nutzen Sie stattdessen die Docker-Demo, wenn Sie Workspace nur lokal testen möchten. Nutzen Sie die Serverinstallation, wenn Sie Workspace direkt auf einem Linux-Server betreiben.

Architektur

Voraussetzungen

Sie benötigen:

• einen Kubernetes-Cluster mit funktionierender IngressClass,
• eine externe oder verwaltete PostgreSQL-Datenbank,
• eine StorageClass für ReadWriteOnce-Volumes,
• eine öffentliche Admin-Domain, zum Beispiel workspace.example.com,
• ein TLS-Zertifikat oder einen automatisierten Zertifikatsaussteller,
• Zugriff auf das Workspace-Server-Image,
• eine Secret-Verwaltung für NUCLEUS_KEY und Datenbankpasswort.

Legen Sie vor dem Rollout fest:

1. Namespace anlegen

Legen Sie zuerst einen eigenen Namespace an:

apiVersion: v1
kind: Namespace
metadata:
  name: workspace

Wenden Sie die Datei an:

kubectl apply -f namespace.yaml

2. Secrets vorbereiten

Workspace benötigt mindestens NUCLEUS_KEY und die PostgreSQL-Zugangsdaten. Erzeugen Sie den NUCLEUS_KEY in Ihrer Secret-Verwaltung und übernehmen Sie ihn nicht aus Beispielen.

apiVersion: v1
kind: Secret
metadata:
  name: workspace-secrets
  namespace: workspace
type: Opaque
stringData:
  NUCLEUS_KEY: "replace-with-your-generated-key"

3. PersistentVolumeClaim anlegen

Workspace speichert die verschlüsselte Konfiguration und Dateien auf einem persistenten Volume. Nutzen Sie eine StorageClass, die zu Ihrem Cluster passt.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: workspace-data
  namespace: workspace
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: standard

Planen Sie die Größe nach Uploads, Dokumenten und erwarteten generierten Dateien. Sichern Sie das Volume zusammen mit der PostgreSQL-Datenbank und dem NUCLEUS_KEY.

4. Deployment anlegen

Starten Sie Workspace mit genau einem Pod, bis Setup, Backup und Rollback geprüft sind. Verwenden Sie mehrere Replikas erst, wenn Ihre Plattform gemeinsamen Storage, Sessions, Rollouts und Health-Checks kontrolliert betreibt.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: workspace
  namespace: workspace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: workspace
  template:
    metadata:
      labels:
        app: workspace
    spec:
      containers:
        - name: workspace
          image: git.schukai.me/releases/nucleus:7.3.0
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 8080
          env:
            - name: NUCLEUS_KEY
              valueFrom:
                secretKeyRef:
                  name: workspace-secrets
                  key: NUCLEUS_KEY
            - name: NUCLEUS_CONFIG
              value: /data/nucleus.config.enc
            - name: NUCLEUS_STORAGE_PATH
              value: /data/storage
          envFrom:
            - secretRef:
                name: workspace-secrets
          volumeMounts:
            - name: data
              mountPath: /data
          readinessProbe:
            httpGet:
              path: /api/v1/ping
              port: http
            initialDelaySeconds: 10
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /api/v1/ping
              port: http
            initialDelaySeconds: 30
            periodSeconds: 20
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: workspace-data

Prüfen Sie nach dem Start die Logs. Beim ersten erfolgreichen Start schreibt Workspace den Logblock SYSTEM INITIALIZED mit Erstzugangsdaten. Sichern Sie diese Werte sofort.

5. Service anlegen

Der Service stellt den Workspace-Pod innerhalb des Clusters bereit:

apiVersion: v1
kind: Service
metadata:
  name: workspace
  namespace: workspace
spec:
  selector:
    app: workspace
  ports:
    - name: http
      port: 80
      targetPort: http

Prüfen Sie danach, ob Kubernetes Endpoints für den Service sieht:

kubectl -n workspace get endpoints workspace

6. Ingress und TLS anlegen

Der Ingress nimmt öffentliche HTTPS-Verbindungen an und leitet sie an den Service weiter. Das Beispiel nutzt generische Ingress-Felder. Ergänzen Sie Annotationen für Ihren Controller, zum Beispiel NGINX, Traefik, HAProxy, Kong oder einen Cloud Load Balancer.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: workspace
  namespace: workspace
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - workspace.example.com
      secretName: workspace-tls
  rules:
    - host: workspace.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: workspace
                port:
                  name: http

Der Ingress muss X-Forwarded-Host und X-Forwarded-Proto korrekt an Workspace weitergeben. Die meisten Ingress-Controller setzen diese Header automatisch. Prüfen Sie die Controller-Dokumentation, wenn Login, Redirects oder absolute URLs auf einen internen Host zeigen.

7. Setup im Browser abschließen

Öffnen Sie die Admin-Domain:

https://workspace.example.com/

Tragen Sie im Setup-Assistenten mindestens diese Werte ein:

localhost ist im Pod der Workspace-Container selbst. Verwenden Sie deshalb immer den echten PostgreSQL-Host oder den Service-Namen Ihrer Datenbank.

8. Start prüfen

Prüfen Sie den technischen Ping über die öffentliche Domain:

curl -sk https://workspace.example.com/api/v1/ping

Prüfen Sie zusätzlich:

• Der Pod ist Ready.
• Die Anmeldung mit dem initialen Administrator funktioniert.
• Die Administrationsoberfläche lädt ohne Redirect auf interne Hosts.
• PostgreSQL ist verbunden.
• /data/nucleus.config.enc liegt auf dem persistenten Volume.
• /data/storage ist beschreibbar.
• TLS-Zertifikat und Hostname passen zur Admin-Domain.
• NUCLEUS_KEY, Datenbankpasswort und Erstzugangsdaten sind gesichert.

9. Backup planen

Sichern Sie immer diese Bestandteile gemeinsam:

• PostgreSQL-Datenbank,
• PersistentVolumeClaim oder Volume-Snapshot,
• NUCLEUS_KEY,
• Secret-Werte für Datenbankzugang und weitere Integrationen.

Testen Sie die Wiederherstellung in einer getrennten Umgebung. Ein Backup ist erst belastbar, wenn Sie daraus eine startfähige Workspace-Instanz wiederhergestellt haben.

10. Update und Rollback durchführen

Planen Sie Updates als kontrollierten Rollout:

1. Prüfen Sie Release-Informationen und Artefakte.
2. Erstellen Sie ein Backup von PostgreSQL, Volume und Secrets.
3. Ändern Sie das Image auf den neuen expliziten Versionstag.
4. Rollen Sie das Deployment aus.
5. Prüfen Sie Pod-Status, Ping, Login und fachliche Smoke-Tests.
6. Rollen Sie bei Fehlern auf den vorherigen Versionstag zurück.

Nutzen Sie für produktive Deployments keine beweglichen Tags. Ein expliziter Versionstag macht Rollbacks nachvollziehbar.

Häufige Fehler

Kubernetes-Betrieb erfolgreich eingerichtet

Die Installation ist abgeschlossen, wenn:

• kubectl -n workspace get deploy workspace verfügbare Replikas zeigt,
• curl -sk https://workspace.example.com/api/v1/ping erfolgreich antwortet,
• die Admin-Anmeldung funktioniert,
• Setup-Werte und System Domain zur öffentlichen Admin-Domain passen,
• PostgreSQL, Volume und Secrets im Backup-Konzept enthalten sind,
• Update- und Rollback-Schritte dokumentiert sind.

Nächste Schritte

• Prüfen Sie TLS und Forwarded-Header mit TLS und Reverse Proxy.
• Pflegen Sie System Domains mit System Domains verstehen.
• Prüfen Sie Health und Readiness mit Diagnose und Readiness.
• Planen Sie Updates und Rollback mit Updates und Rollback.