So richten Sie Collabora CODE auf Kubernetes mit Helm ein

Eine Collabora Online-Seite kann leer bleiben oder melden, dass der Office-Server nicht verfügbar ist, selbst wenn der CODE-Pod ausgeführt wird. Ein fehlerfreier Pod ist nur ein Teil der Einrichtung: Browser und Ihre WOPI-Anwendung müssen Collabora über den öffentlichen Hostnamen erreichen, TLS- und Proxy-Einstellungen müssen übereinstimmen, und Collabora muss dem WOPI-Host vertrauen. Das offizielle Collabora Helm-Chart stellt den Server in Kubernetes bereit; es installiert oder konfiguriert weder Nextcloud, ownCloud noch einen anderen WOPI-Host.

Diese Anleitung verwendet das von Collabora bereitgestellte Helm-Chart mit einem NGINX-Ingress-Beispiel. Ersetzen Sie die Beispieldomains durch Ihre eigenen. CODE steht für Collabora Online Development Edition und ist für Evaluierungszwecke, den privaten Gebrauch und kleine Teams gedacht. Collabora empfiehlt diese Version nicht für Produktionsumgebungen, die eine stabile, unterstützte Version benötigen. Für Produktionsumgebungen sollten Sie das unterstützte Collabora Online-Angebot sowie dessen Lizenz- und Supportbedingungen prüfen.

Was Sie vor der Installation benötigen

• Ein funktionierender Kubernetes-Cluster kubectlund Helm 3 mit Zugriff auf den Cluster.
• Ein Ingress-Controller ist im Cluster installiert. Das folgende Beispiel verwendet ingress-nginx; das Collabora-Diagramm dokumentiert auch HAProxy und unterstützt weitere Routing-Konfigurationen.
• Ein DNS-Name, der beispielsweise office.example.comauf die öffentliche Eingangsadresse verweist, plus ein TLS-Zertifikat, das als Kubernetes Secret im Collabora-Namespace gespeichert ist.
• Eine WOPI-Anwendung wie Nextcloud mit einer URL wie cloud.example.com. Collabora muss die WOPI-Anwendung erreichen können, und die Anwendung sowie die Browser der Benutzer müssen Collabora erreichen können.
• Ein klarer TLS-Plan. Dieses Beispiel beendet HTTPS am Eingang und sendet HTTP an den Collabora-Dienst innerhalb des Clusters.

Für eine schnelle Bereitstellung zu Hause oder zu Testzwecken sorgt ein einzelner CODE-Pod für einfaches Routing. Mehrere Replikate können die Kapazität erhöhen, aber Collaboras Kubernetes-Leitfaden empfiehlt ein WOPISrc-basiertes Load-Balancing, damit Bearbeitungssitzungen für dasselbe Dokument im selben Pod landen. Skalieren Sie die Replikate erst, nachdem Sie sichergestellt haben, dass Ihr Ingress-Controller die benötigte Affinität bereitstellen kann.

Schritt 1: Offizielle Charts hinzufügen und eine Version auswählen

Collabora veröffentlicht sein Chart aus dem CollaboraOnline-Projekt. Die Release-Seite listet aktuell Chart-Version 1.3.5 auf (Stand: 6. Oktober 2026). Prüfen Sie die in Ihrer Umgebung verfügbaren Versionen und fixieren Sie die Chart-Version, damit ein späteres Repository-Update das bereitgestellte Chart nicht unbemerkt ändert.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

Das offizielle Chart-Repository ist nützlich, um die aktuellen Standardeinstellungen zu überprüfen, bevor man Überschreibungen schreibt:

helm show values collabora/collabora-online --version 1.3.5

Wenn Ihr Repository beim Befolgen dieser Anleitung ein neueres, kompatibles Chart auflistet, überprüfen Sie dessen Versionshinweise und Werte, bevor Sie diese Version verwenden. Die Chart-Version und die Version des CODE-Anwendungsabbilds sind zwar verwandte Versionsangaben, aber nicht dieselbe Einstellung.

Schritt 2: Erstellen Sie einen Namespace und schützen Sie das Administratorpasswort.

Erstellen Sie den Namespace und ein Kubernetes-Secret für die optionalen Collabora-Administratoranmeldeinformationen des Charts. Ersetzen Sie das Platzhalterpasswort durch ein sicheres Secret oder erstellen Sie das Secret über den Secret Manager Ihrer Organisation oder den GitOps-Secret-Workflow. Speichern Sie kein echtes Passwort in der Konfigurationsdatei values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

Das Chart unterstützt das Referenzieren eines vorhandenen Secrets. Dadurch wird vermieden, dass das Administratorpasswort direkt in die Helm-Wertedatei eingetragen wird. Das Secret sollte auf den Namespace und die Benutzer oder Dienstkonten beschränkt sein, die diese Bereitstellung verwalten.

Schritt 3: Hostnamen, WOPI-Host und Ingress konfigurieren

Erstellen Sie eine Datei mit dem Namen collabora-values.yaml. Dieses Beispiel setzt ingress-nginx, ein TLS-Secret mit dem Namen office-example-com-tlsund Nextcloud unter voraus https://cloud.example.com. Die Aliasgruppe muss den WOPI-Anwendungshost angeben, den Collabora kontaktieren darf; es handelt sich nicht um den öffentlichen Collabora-Hostnamen.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

Das dokumentierte Beispiel im Chart verwendet aliasgroupsdie entsprechenden SSL-Parameter, um den WOPI-Host zuzulassen, wenn ein Reverse-Proxy TLS beendet. In dieser Konfiguration office.example.comnutzt externer Datenverkehr HTTPS, während der Ingress den Datenverkehr innerhalb des Clusters über HTTP an Collabora weiterleitet. Wenn Ihr Ingress TLS-Passthrough oder ein anderes internes Protokoll verwendet, kopieren Sie diese SSL-Flags nicht einfach, sondern passen Sie sie an den tatsächlichen TLS-Pfad und die aktuellen Werte im Chart an.

Stellen Sie sicher, dass das TLS-Geheimnis im collaboraNamespace vorhanden ist. Wenn Sie einen anderen Ingress-Controller verwenden, ersetzen Sie die Klasse und die Annotationen durch die entsprechenden dokumentierten Werte dieses Controllers. Aktivieren Sie WebSocket-Traffic und erlauben Sie dauerhafte Verbindungen; die Standardeinstellungen der Controller können variieren.

Schritt 4: Diagramm rendern und installieren

Rendern Sie zuerst die Manifeste, um YAML-Fehler abzufangen, und überprüfen Sie die generierten Ingress-, Service- und Workload-Einstellungen. Installieren Sie anschließend die angeheftete Chart-Version.

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

Beobachten Sie die Ressourcen, sobald sie verfügbar sind:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Warten Sie, bis der Pod den Status „Bereit“ erreicht hat, bevor Sie die WOPI-Anwendung verbinden. Bleibt der Status „Ausstehend“, prüfen Sie, ob der Cluster über ausreichend planbare CPU- und Arbeitsspeicherressourcen verfügt und ob Knotenselektoren, Taints oder Ressourcenkontingente die Platzierung verhindern. Die Tabelle überlässt die Festlegung von Ressourcenanforderungen und -grenzen dem Operator. Die README-Datei von Collabora enthält beispielhaft höhere Ressourcenwerte für Produktionsumgebungen; die tatsächliche Dimensionierung hängt jedoch von der Anzahl gleichzeitiger Bearbeitungen und der Dokumentlast ab.

Schritt 5: Nextcloud oder einen anderen WOPI-Host verbinden

Öffnen Sie die Office- oder Collabora-Einstellungen Ihrer WOPI-Anwendung und geben Sie die URL des externen Dienstes ein https://office.example.com. In Nextcloud beschreibt das Administrationshandbuch, wie Sie die URL des Collabora-Online-Servers in den Office-Administrationseinstellungen festlegen. Überprüfen Sie außerdem die Nextcloud-Liste der zulässigen WOPI-Anfragen, falls Ihre Konfiguration die Verbindung bestimmter Hosts einschränkt. Die Adresse muss sowohl für Endbenutzer-Browser als auch für den Anwendungsserver, der WOPI-Anfragen sendet, erreichbar sein.

Schlägt die Verbindung mit einer Fehlermeldung wie „Nicht autorisierter WOPI-Host“ fehl, vergleichen Sie die tatsächliche WOPI-Host-URL mit der Referenz-URL collabora.aliasgroups. Überprüfen Sie Schema, Hostname und Port und fügen Sie gegebenenfalls alternative, gültige Hostnamen hinzu. Vermeiden Sie allgemeine Hostmuster, es sei denn, Sie verstehen deren Auswirkungen. Wenn Sie mehrere WOPI-Anwendungen verwenden, halten Sie sich für jeden Host an die in der Tabelle dokumentierte Aliasgruppenstruktur, anstatt jede Domain zuzulassen.

Wann sollte man über eine Kapsel hinaus skalieren?

Für einen kleinen Test vermeidet eine Replik mit deaktiviertem Autoscaling die Routing-Komplexität. Bei mehreren Replikaten zeigt die README-Datei des Collabora-Charts die NGINX-Affinität basierend auf dem WOPISrcAbfrageargument an. Fügen Sie die dokumentierte Annotation zum Ingress hinzu, wenn Sie ingress-nginx verwenden.

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

Dies leitet Anfragen für dasselbe Dokument an denselben Backend-Pod weiter, was für die gemeinsame Bearbeitung und Zwischenablage wichtig ist. Prüfen Sie die Dokumentation Ihrer genauen Ingress-Controller-Version; eine von ingress-nginx unterstützte Annotation ist nicht automatisch für HAProxy, Traefik oder eine Gateway-API-Implementierung gültig. Testen Sie nach der Aktivierung weiterer Replikate oder der automatischen Skalierung gleichzeitige Bearbeitungen desselben Dokuments und beobachten Sie die Collabora- und Ingress-Zugriffsprotokolle. Ressourcendimensionierung, Sitzungsverhalten und Hochverfügbarkeit müssen workloadspezifisch validiert werden.

Überprüfen Sie die Bereitstellung von außen.

1. Bestätigen Sie, dass Kubernetes den Pod als bereit meldet und dass der Service und der Ingress vorhanden sind: kubectl get pods,svc,ingress -n collabora.
2. Überprüfen Sie den öffentlichen Discovery-Endpunkt. Er sollte XML zurückgeben und keine Browser- oder Proxy-Fehlermeldung anzeigen:

   curl -fsS https://office.example.com/hosting/discovery | head -c 300

3. Öffnen Sie die WOPI-Anwendung und bearbeiten Sie ein Testdokument. Prüfen Sie, ob der Editor geladen wird, die Änderungen gespeichert werden und beim erneuten Öffnen des Dokuments der gespeicherte Inhalt angezeigt wird.
4. Wenn Sie mehrere Replikate verwenden, öffnen Sie dasselbe Dokument in zwei Sitzungen und prüfen Sie, ob beide ohne wiederholte Verbindungsabbrüche zusammenarbeiten können. Dies hilft, fehlende Sitzungsaffinität zu identifizieren.
5. Überprüfen Sie die Protokolle auf TLS-, WOPI-Autorisierungs- oder Upstream-Fehler:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   Falls das Diagramm eine anders benannte Arbeitslast erzeugt, verwenden Sie kubectl get deployments -n collaboraden tatsächlichen Namen und ersetzen Sie ihn entsprechend.

Eine erfolgreiche Discovery-Antwort bestätigt, dass der öffentliche Endpunkt Collabora-Metadaten bereitstellt; sie beweist jedoch nicht, dass die WOPI-Authentifizierung oder das Speichern von Dokumenten funktioniert. Der End-to-End-Dokumententest ist die abschließende Prüfung.

Häufige Fehlerquellen

• Wenn Ingress den Statuscode 404 oder 502 zurückgibt, überprüfen Sie DNS, Ingress-Klasse, TLS-Secret und Service-Endpunkte. Stellen Sie sicher, dass Ingress den Collabora-Service über den Service-Port des Charts erreichen kann.
• Die Erkennung funktioniert, aber der Editor bleibt leer: Überprüfen Sie die Browserkonsole und die Proxy-Protokolle. Prüfen Sie die HTTPS-Terminierungseinstellungen, die WebSocket-Verarbeitung und lange Anfrage-Timeouts.
• Nicht autorisierter WOPI-Host: Erlauben Sie den Ursprung der WOPI-Anwendung in aliasgroups; ersetzen Sie nicht den Hostnamen des Büroservers.
• Pod wird neu gestartet oder entfernt: Überprüfen Sie kubectl describe poddie Containerprotokolle und legen Sie dann realistische Ressourcenanforderungen und -grenzen für den verfügbaren Cluster fest.
• Die Bearbeitung wird nach dem Hinzufügen von Replikaten instabil: Überprüfen Sie die WOPISrc-basierte Affinität und stellen Sie sicher, dass der Controller das Abfrageargument beim Weiterleiten von Anfragen beibehält.

Sobald das Chart installiert, der Discovery-Endpunkt erreichbar und ein Dokument erfolgreich über die WOPI-Anwendung geöffnet und gespeichert wurde, funktioniert die CODE-Bereitstellung. Halten Sie die Chart-Version fest und wiederholen Sie diese Prüfungen nach Chart-Upgrades, Ingress-Änderungen oder Skalierungsänderungen.

Offizielle Referenzen

• Collabora-gepflegtes Kubernetes Helm-Chart und Bereitstellungsleitfaden
• Collabora Helm-Diagrammwerte
• Collabora-Chart-Veröffentlichungen
• Leitfaden zur Collabora Online Development Edition (CODE).
• Nextcloud Office-Konfigurationshandbuch
• ingress-nginx-Annotationsdokumentation
• Helm-Installationsbefehlsreferenz