TLS und Reverse Proxy

Klären Sie zuerst, wo TLS in Ihrer Umgebung endet. Danach richten Sie den öffentlichen HTTPS-Zugriff über Reverse Proxy, Ingress, Load Balancer oder direktes TLS ein.

Prüfen Sie dabei:

wo TLS in Ihrer Umgebung endet,
welches Zertifikat Clients sehen,
welche Header Workspace vom Proxy benötigt,
wann ein selbstsigniertes Zertifikat nur für lokale Tests passt.

Empfohlener Weg

Beenden Sie TLS in produktiven Umgebungen am Reverse Proxy oder Ingress. Der Proxy verwaltet Zertifikate, nimmt HTTPS von außen an und leitet intern an Workspace weiter.

Setzen Sie dabei:

text

X-Forwarded-Host: workspace.example
X-Forwarded-Proto: https

Workspace nutzt diese Werte, um öffentliche URLs, Weiterleitungen und den Systemzugang korrekt zu erzeugen.

Zertifikat wählen

Szenario	Geeigneter Weg
Lokale Demo	selbstsigniertes Zertifikat aus dem Setup-Assistenten
Interne Testumgebung	internes Zertifikat Ihrer Organisation
Öffentlich erreichbare Umgebung	vertrauenswürdiges Zertifikat am Reverse Proxy
Automatisierte Plattform	Zertifikatsverwaltung von Ingress, Load Balancer oder Let’s Encrypt

Für lokale Tests kann der Setup-Assistent ein selbstsigniertes Zertifikat erzeugen. Die Verbindung ist verschlüsselt, Browser und CLI-Clients vertrauen dem Zertifikat aber nicht automatisch.

Für curl-Tests gegen die lokale Docker-Demo übergeben Sie das erzeugte Zertifikat ausdrücklich als Vertrauensanker:

bash

curl --cacert ./data/nucleus.crt \
  https://localhost:8443/health/ready

Schalten Sie die TLS-Prüfung nicht mit curl -k oder curl --insecure ab. Verwendet Ihre Organisation eine interne Zertifizierungsstelle, installieren Sie deren CA-Zertifikat im Truststore des Clients oder übergeben es für eine gezielte Prüfung mit curl --cacert /pfad/zur/ca.pem https://workspace.example/api/v1/ping.

TLS im Workspace-Server

Wenn Workspace selbst TLS bereitstellt, geben Sie im Setup-Assistenten Zertifikats- und Schlüsseldateien an oder erzeugen für lokale Tests ein selbstsigniertes Zertifikat.

Der Host im TLS-Schritt ist der Name im Zertifikat. Er ist nicht dasselbe wie System Domains (CSV).

Bei Containerbetrieb müssen Zertifikat und privater Schlüssel im Container sichtbar sein. Mounten Sie Dateien zum Beispiel read-only:

yaml

services:
  nucleus:
    volumes:
      - nucleus-data:/data
      - ./certs:/certs:ro

Wählen Sie im Setup dann Container-Pfade:

Feld	Wert
Zertifikatsdatei	`/certs/workspace.crt`
Schlüsseldatei	`/certs/workspace.key`

Der private Schlüssel muss ohne interaktive Passphrase lesbar sein, damit die Laufzeit automatisch starten kann.

System Domains

System Domains (CSV) steuert, über welche Hostnamen die Administrationsoberfläche vor der Mandantenauswahl erreichbar ist. Tragen Sie dort Hostnamen ohne Protokoll, Pfad oder Port ein.

Weitere Details stehen unter System-Domains verstehen.

Häufige Fehler

Fehlerbild	Ursache
Browser zeigt Zertifikatswarnung	selbstsigniertes oder nicht vertrauenswürdiges Zertifikat
`tls: unknown certificate` im Log	Client hat das lokale Zertifikat abgelehnt
Weiterleitungen zeigen auf interne URL	`X-Forwarded-Host` oder `X-Forwarded-Proto` fehlen oder sind falsch
Systemzugang wird nicht erkannt	öffentliche Admin-Domain fehlt in `System Domains (CSV)`

Wenn ein Client das lokale Zertifikat ablehnt, kann Workspace trotzdem korrekt laufen. Prüfen Sie die Docker-Demo mit ./start.sh doctor und dem lokalen Vertrauensanker. Browser, Betriebssystem, Host-CLI und MCP-Prozess konfigurieren Sie getrennt nach Docker-Demo in 10 Minuten. Für produktive Umgebungen verwenden Sie ein vertrauenswürdiges Zertifikat.

Nächste Schritte

Pflegen Sie öffentliche System-Domains mit System-Domains verstehen.
Prüfen Sie Betrieb und Readiness mit Diagnose und Readiness.
Planen Sie Updates und Rollback mit Updates und Rollback.
Prüfen Sie Container-Ingress mit Container und Ingress, wenn Workspace hinter orchestriertem Ingress läuft.