Collabora online auf Kubernetes-Knoten ausführen

Für eine Collabora Online-Bereitstellung mit mehreren Knoten verwenden Sie das Collabora Kubernetes Helm-Chart hinter einem Ingress- oder Reverse-Proxy, der sicherstellt, dass alle Anfragen für dasselbe Dokument im selben Collabora-Pod bleiben. Diese Sitzungsaffinität ist unerlässlich: Herkömmliches Round-Robin-Balancing kann dazu führen, dass Bearbeitungs- und Zwischenablage-Anfragen eines Benutzers an verschiedene Pods gesendet werden und die gemeinsame Bearbeitung beeinträchtigt wird. Das folgende Beispiel verwendet drei Replikate, NGINX Ingress und eine feste Anzahl an Replikaten; ersetzen Sie die Beispiel-Hostnamen und das TLS-Geheimnis durch Ihre eigenen.

Was benötigen Sie, bevor Sie Replikate hinzufügen?

Sie benötigen einen laufenden Kubernetes-Cluster mit mindestens zwei Worker-Knoten, Helm, einen Ingress-Controller, der die erforderliche Affinitätsregel unterstützt, einen DNS-Namen (z. B. `<collabora-name>.com`) office.example.comund ein TLS-Zertifikat für diesen Namen. Nextcloud muss von jedem Collabora-Pod über seinen öffentlichen WOPI-Ursprung (z. B. `<collabora-name>.com`) erreichbar sein https://cloud.example.com. CODE und Nextcloud sind separate Dienste; diese Anleitung konfiguriert die Collabora-Ebene und verbindet anschließend deren öffentliche URL mit Nextcloud Office.

Verwenden Sie die im Collabora-Chart dokumentierte Multi-Replica-Konfiguration, anstatt mehrere unabhängige Docker-Container hinter einem generischen Load Balancer zu platzieren. Ein Load Balancer, der Anfragen unabhängig von der WOPI-Quelle verteilt, kann Sitzungen unterbrechen. Diese Anleitung orientiert sich an den offiziellen Anweisungen für das Collabora Helm-Chart vom 10. Oktober 2026. Da sich die Werte im Chart ändern können, überprüfen Sie bitte die Werte für die von Ihnen geplante Chart-Version.

1. Replikate, Ingress-Affinität und den WOPI-Host konfigurieren

Fügen Sie das Chart-Repository hinzu, aktualisieren Sie dessen Index und überprüfen Sie die aktuellen Standardeinstellungen des Charts, bevor Sie Ihre Überschreibungsdatei schreiben:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm show values collabora/collabora-online

Erstellen Sie die Anwendung my_values.yamlmit den unten stehenden Kerneinstellungen. Das Beispiel verwendet die in der README-Datei des Collabora-Diagramms dargestellte NGINX-Ingress-Annotation. Es verwendet Hashing, WOPISrcsodass Anfragen, die zu einem Dokument gehören, denselben Pod erreichen. Außerdem wird öffentliches TLS am Ingress beendet; die angezeigten Collabora-Servereinstellungen beziehen sich auf dieses Proxy-terminierte TLS-Muster.

replicaCount: 3
autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    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-tls
      hosts:
        - office.example.com

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

Der aliasgroupsEintrag ist der Nextcloud-WOPI-Host, nicht der Collabora-Hostname. Halten Sie ihn kurz und verwenden Sie genau das Schema, den Hostnamen und den Port, die Nextcloud angibt. Das Ingress-TLS-Secret muss im Ingress-Namespace vorhanden sein und ein gültiges Zertifikat enthalten office.example.com. Falls TLS an anderer Stelle terminiert, verwenden Sie das entsprechende Proxy-Muster in der Chart-Dokumentation, anstatt die beiden extra_paramsFlags einfach zu kopieren.

Es gibt eine versionsabhängige Einschränkung bezüglich der automatischen Skalierung: Im Beispiel der Chart-README ist die automatische Skalierung deaktiviert, und es wird davor gewarnt, dass die Skalierung die gemeinsame Bearbeitung und das Kopieren/Einfügen beeinträchtigen kann. In der aktuell veröffentlichten Wertedatei ist die automatische Skalierung jedoch standardmäßig aktiviert. Um einen vorhersehbaren initialen Cluster zu erhalten, deaktivieren Sie die automatische Skalierung explizit und wählen Sie eine feste Anzahl von Replikaten. Überprüfen Sie die Hinweise zur jeweiligen Chart-Version und testen Sie das Hoch- und Herunterskalieren in realen Bearbeitungssitzungen erneut, bevor Sie die automatische Skalierung erneut in Betracht ziehen.

2. Installieren Sie das Chart und überprüfen Sie die Pod-Platzierung.

Installieren Sie das Chart in einem dedizierten Namespace. Das offizielle Chart-Repository dokumentiert dieses Befehlsmuster:

helm install --create-namespace \
  --namespace collabora \
  collabora-online collabora/collabora-online \
  -f my_values.yaml

Überprüfen Sie anschließend, ob die Bereitstellung die gewünschte Anzahl an Replikaten erreicht hat, und sehen Sie nach, welche Worker-Knoten die Pods hosten:

kubectl get pods -n collabora -o wide
kubectl get ingress -n collabora
helm status collabora-online -n collabora

Stellen Sie sicher, dass alle drei Pods bereit sind, der Ingress den erwarteten Host verwendet und Replikate auf die Worker-Knoten verteilt sind, falls Ausfallsicherheit auf Knotenebene erforderlich ist. Die Anzahl der Replikate allein garantiert nicht, dass Kubernetes Pods auf separaten Knoten platziert. Die offizielle Chart-Vorlage stellt Einstellungen für Knotenselektor, Affinität und Toleranz bereit. Konfigurieren Sie geeignete Scheduling-Regeln für Ihren Cluster und überprüfen Sie das gerenderte Chart, bevor Sie sich darauf verlassen. Falls Ihre Chart-Version die benötigte Richtlinie nicht bereitstellt, verwenden Sie eine unterstützte Chart-Erweiterung oder eine Anpassung der Kubernetes-Bereitstellung, anstatt von einer Verteilung der Pods auszugehen.

3. Nextcloud verbinden und Dokumentenaffinität überprüfen.

Installieren oder aktivieren Sie in Nextcloud die Nextcloud Office- App und öffnen Sie anschließend die Administrationseinstellungen → Office . Wählen Sie den externen Collabora-Server aus und geben Sie die Server-URL ein https://office.example.com. Die Server-URL ist der öffentliche TLS-Endpunkt, der sowohl vom Nextcloud-Server als auch von den Browsern der Benutzer erreicht werden kann. Geben Sie keine Pod-IP-Adresse oder interne Dienstadresse ein.

Öffnen Sie eine Test-DOCX- oder ODT-Datei in Nextcloud. Bearbeiten Sie diese in zwei separaten Benutzersitzungen und prüfen Sie, ob beide Benutzer die Änderungen sehen. Überprüfen Sie außerdem die Entwicklertools Ihres Browsers oder die Ingress-Logs auf WebSocket-Fehler; der Ingress muss die dauerhafte Editorverbindung aufrechterhalten. Falls die Anfragen für eine Datei auf mehrere Pods verteilt sind, stellen Sie sicher, dass der WOPISrcAbfrageparameter an der Stelle vorhanden ist, an der der Ingress die Hash-Regel anwendet, und dass der installierte Ingress-Controller die Annotation berücksichtigt.

Was beweist ein gesunder Cluster?

Ein erfolgreicher Test bestätigt, dass Nextcloud den Collabora-Endpunkt erreichen und ein Dokument über den konfigurierten Ingress bearbeitet werden kann. Er beweist jedoch nicht, dass jede aktive Sitzung einen Pod- oder Knotenausfall übersteht. Der Bearbeitungsstatus wird vom Pod verwaltet, der das jeweilige Dokument bereitstellt. Daher kann ein Ausfall dazu führen, dass Benutzer die Verbindung wiederherstellen oder eine Datei erneut öffnen müssen, selbst wenn andere Replikate verfügbar sind. Testen Sie Wartungs- und Ausfallszenarien mit unkritischen Dokumenten und planen Sie Upgrades so, dass langlebige WebSocket-Sitzungen gezielt behandelt werden.

Die aktuelle Syntax und mögliche Einschränkungen finden Sie in der offiziellen README-Datei und den Wertedateien des Collabora Kubernetes Helm Charts , der veröffentlichten Wertedatei des Charts sowie im Konfigurationshandbuch für Nextcloud Office . Überprüfen Sie die Einstellungen anhand der installierten Chart-Version, da die Beispiele und Standardwerte des Repositorys möglicherweise nicht identisch sind.