Hoe Collabora CODE op Kubernetes in te stellen met Helm

Een Collabora Online-pagina kan leeg blijven of melden dat de kantoorserver niet beschikbaar is, zelfs nadat de CODE-pod actief is. Een goed functionerende pod is slechts een onderdeel van de configuratie: de browser en uw WOPI-applicatie moeten Collabora via de openbare hostnaam kunnen bereiken, de TLS- en proxy-instellingen moeten overeenkomen en Collabora moet de WOPI-host vertrouwen. De officiële Collabora Helm-grafiek implementeert de server in Kubernetes; deze installeert of configureert geen Nextcloud, ownCloud of een andere WOPI-host voor u.

Deze handleiding maakt gebruik van de door Collabora beheerde Helm-grafiek met een NGINX Ingress-voorbeeld. Vervang de voorbeelddomeinen door uw eigen domeinen. CODE staat voor Collabora Online Development Edition, bedoeld voor evaluatie, thuisgebruik en kleine teams; Collabora geeft aan dat deze versie niet wordt aanbevolen voor productieomgevingen die een stabiele, ondersteunde release vereisen. Voor productieworkloads raden we aan om het ondersteunde Collabora Online-aanbod en de bijbehorende licentie- en ondersteuningsvoorwaarden te evalueren.

Wat je nodig hebt voordat je begint met installeren

• Een werkend Kubernetes-cluster kubectlen Helm 3 met toegang tot het cluster.
• Een Ingress-controller is in het cluster geïnstalleerd. Het onderstaande voorbeeld gebruikt ingress-nginx; de Collabora-grafiek documenteert ook HAProxy en ondersteunt andere routeringsconfiguraties.
• Een DNS-naam die office.example.comverwijst naar het openbare inkomende adres, plus een TLS-certificaat dat is opgeslagen als een Kubernetes Secret in de Collabora-namespace.
• Een WOPI-applicatie zoals Nextcloud met een URL zoals cloud.example.com.Collabora moet de WOPI-applicatie kunnen bereiken, en de applicatie en de browsers van de gebruikers moeten Collabora kunnen bereiken.
• Een duidelijk TLS-plan. Dit voorbeeld beëindigt HTTPS bij de ingang en stuurt HTTP door naar de Collabora-service binnen het cluster.

Voor een snelle implementatie thuis of voor testdoeleinden is één CODE-pod voldoende om de routing eenvoudig te houden. Meerdere replica's kunnen de capaciteit vergroten, maar de Kubernetes-handleiding van Collabora benadrukt de noodzaak van load balancing op basis van WOPISrc, zodat bewerkingssessies voor hetzelfde document dezelfde pod bereiken. Schaal replica's niet op voordat u hebt gecontroleerd of uw ingress controller de benodigde affiniteit kan bieden.

Stap 1: Voeg de officiële hitlijst toe en selecteer een versie.

Collabora publiceert zijn chart vanuit het CollaboraOnline-project. Op de releasepagina staat momenteel chartversie 1.3.5 vermeld (gecontroleerd op 6 oktober 2026). Controleer de beschikbare versies in uw omgeving en stel de chartversie in, zodat een latere repository-update de chart die u implementeert niet ongemerkt wijzigt.

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

De officiële chart-repository is handig om de huidige standaardinstellingen te controleren voordat je ze wijzigt:

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

Als uw repository een nieuwere, compatibele grafiek vermeldt wanneer u deze handleiding volgt, bekijk dan de release-opmerkingen en waarden ervan voordat u die versie gebruikt. De grafiekversie en de CODE-applicatie-imageversie zijn gerelateerde release-inputs, maar het zijn niet dezelfde instellingen.

Stap 2: Maak een naamruimte aan en beveilig het beheerderswachtwoord.

Maak de namespace en een Kubernetes Secret aan voor de optionele Collabora-beheerdersgegevens van de chart. Vervang het placeholder-wachtwoord door een sterk geheim, of maak de Secret aan via de secret manager van uw organisatie of de GitOps secret workflow. Sla geen echt wachtwoord op in de configuratie 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'

De grafiek ondersteunt het verwijzen naar een bestaand geheim. Door dit in te schakelen, hoeft het beheerderswachtwoord niet rechtstreeks in het Helm-waardenbestand te worden geplaatst. Houd het geheim beperkt tot de namespace en de gebruikers of serviceaccounts die deze implementatie beheren.

Stap 3: Configureer de hostnaam, WOPI-host en ingress

Maak een bestand aan met de naam collabora-values.yaml. Dit voorbeeld gaat ervan uit dat ingress-nginx, een TLS-geheim met de naam office-example-com-tlsen Nextcloud op https://cloud.example.com. De aliasgroep moet de naam zijn van de WOPI-applicatiehost waarmee Collabora contact mag opnemen; dit is niet de openbare hostnaam van Collabora.

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

Het voorbeeld in de grafiek laat zien aliasgroupsdat de WOPI-host en deze SSL-parameters worden gebruikt wanneer een reverse proxy TLS beëindigt. In deze configuratie office.example.comgebruikt extern verkeer HTTPS, terwijl de ingress verkeer binnen het cluster via HTTP doorstuurt naar Collabora. Als uw ingress TLS-passthrough of een ander intern protocol gebruikt, kopieer deze SSL-vlaggen dan niet blindelings; pas ze aan zodat ze overeenkomen met het daadwerkelijke TLS-pad en de huidige waarden in de grafiek.

Controleer of het TLS-geheim in de collaboranamespace aanwezig is. Als u een andere ingress-controller gebruikt, vervang dan de klasse en annotaties door de gedocumenteerde equivalenten van die controller. Houd websocketverkeer ingeschakeld en sta langdurige verbindingen toe; de ​​standaardinstellingen variëren per controller.

Stap 4: De grafiek renderen en installeren

Genereer eerst de manifesten om YAML-fouten op te sporen en controleer de gegenereerde Ingress-, Service- en workload-instellingen. Installeer vervolgens de vastgepinde chart-release:

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

Bekijk de resources zodra ze starten:

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

Wacht tot de pod gereed is voordat u de WOPI-applicatie verbindt. Als deze in de status 'in behandeling' blijft, controleer dan of het cluster voldoende planbare CPU en geheugen heeft en of er knooppuntselectoren, taints of resourcequota zijn die plaatsing belemmeren. De grafiek laat de resourceaanvragen en -limieten over aan de operator; de README van Collabora geeft grotere voorbeeldwaarden voor resources in productieomgevingen, maar de werkelijke dimensionering is afhankelijk van de gelijktijdige bewerkings- en documentbelasting.

Stap 5: Verbind Nextcloud of een andere WOPI-host

Open de Office- of Collabora-instellingen van uw WOPI-applicatie en voer de URL van de externe service in https://office.example.com. In Nextcloud beschrijft de beheerdershandleiding hoe u de URL van de Collabora Online-server instelt in de Office-beheerinstellingen. Controleer ook de Nextcloud WOPI-verzoeklijst als uw configuratie beperkingen oplegt aan welke hosts verbinding mogen maken. Het adres moet bereikbaar zijn voor zowel de browsers van eindgebruikers als voor de applicatieserver die WOPI-verzoeken uitvoert.

Als de verbinding mislukt met een bericht als 'ongeautoriseerde WOPI-host' of iets dergelijks, vergelijk dan de daadwerkelijke WOPI-host-URL met de opgegeven URL collabora.aliasgroups. Controleer het schema, de hostnaam en de poort en voeg eventuele legitieme alternatieve hostnamen bewust toe. Vermijd brede hostpatronen, tenzij u de gevolgen ervan begrijpt. Als u meer dan één WOPI-applicatie gebruikt, volg dan de in de tabel beschreven aliasgroepstructuur voor elke host in plaats van elk domein toe te staan.

Wanneer moet je opschalen naar meer dan één pod?

Voor een kleinschalige test volstaat één replica met uitgeschakelde autoscaling om complexe routeringsproblemen te voorkomen. Voor meerdere replica's toont de README van de Collabora-grafiek de NGINX-affiniteit op basis van het WOPISrcquery-argument. Voeg de gedocumenteerde annotatie toe aan de ingress wanneer u ingress-nginx gebruikt:

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

Dit zorgt ervoor dat verzoeken voor hetzelfde document naar dezelfde backend-pod worden gestuurd, wat belangrijk is voor gezamenlijk bewerken en klembordverzoeken. Raadpleeg de documentatie voor uw specifieke ingress-controller-versie; een annotatie die door ingress-nginx wordt ondersteund, is niet automatisch geldig voor HAProxy, Traefik of een Gateway API-implementatie. Nadat u meer replica's of autoscaling hebt ingeschakeld, test u gelijktijdige bewerkingen aan hetzelfde document en controleert u de Collabora-logboeken en de ingress-toegangslogboeken. Resourcegrootte, sessiegedrag en hoge beschikbaarheid vereisen workloadspecifieke validatie.

Controleer de implementatie vanaf de buitenkant.

1. Controleer of Kubernetes de pod als 'Ready' rapporteert en of de Service en Ingress bestaan: kubectl get pods,svc,ingress -n collabora.
2. Controleer het openbare discovery-eindpunt. Het zou XML moeten retourneren in plaats van een browser- of proxyfout.

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

3. Open de WOPI-applicatie en bewerk een testdocument. Controleer of de editor laadt, de wijzigingen worden opgeslagen en of de opgeslagen inhoud zichtbaar is wanneer u het document opnieuw opent.
4. Als u meerdere replica's gebruikt, open dan hetzelfde document in twee sessies en controleer of beide sessies probleemloos kunnen samenwerken zonder herhaaldelijk opnieuw verbinding te hoeven maken. Dit helpt bij het opsporen van ontbrekende sessie-affiniteit.
5. Controleer de logbestanden op TLS-, WOPI-autorisatie- of upstream-fouten:

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

   Als de grafiek een workload met een andere naam aanmaakt, gebruik kubectl get deployments -n collaboradan de daadwerkelijke naam en vervang deze.

Een succesvolle ontdekkingsreactie bevestigt dat het openbare eindpunt Collabora-metadata levert; het bewijst echter niet dat WOPI-authenticatie of het opslaan van documenten werkt. De end-to-end documenttest is de laatste controle.

Veelvoorkomende faalpunten

• Ingress retourneert een 404- of 502-fout: controleer de DNS, de ingress-klasse, het TLS-geheim en de service-eindpunten. Bevestig dat ingress de Collabora-service kan bereiken op de servicepoort van de chart.
• De ontdekking werkt, maar de editor blijft leeg: controleer fouten in de browserconsole en proxylogboeken. Controleer de HTTPS-terminatie-instellingen, de afhandeling van websockets en lange time-outs voor verzoeken.
• Niet-geautoriseerde WOPI-host: sta de oorsprong van de WOPI-applicatie toe in aliasgroups; vervang de hostnaam van de kantoorserver niet.
• Als een pod opnieuw opstart of wordt verwijderd: inspecteer kubectl describe podde containerlogboeken en stel vervolgens realistische resourceaanvragen en -limieten in voor het beschikbare cluster.
• Bewerken wordt instabiel na het toevoegen van replica's: controleer de op WOPISrc gebaseerde affiniteit en bevestig dat de controller het queryargument behoudt bij het routeren van verzoeken.

Als de grafiek is geïnstalleerd, het ontdekkingseindpunt bereikbaar is en een echt document succesvol is geopend en opgeslagen via de WOPI-applicatie, werkt de kernimplementatie van CODE. Houd de grafiekversie vast en herhaal deze controles na grafiekupgrades, wijzigingen in de inkomende gegevens of schaalwijzigingen.

Officiële referenties

• Handleiding voor het implementeren van Kubernetes Helm-grafiek en -implementatie, onderhouden door Collabora.
• Collabora Helm-grafiekwaarden
• Collabora-hitlijstreleases
• Collabora Online Development Edition (CODE) handleiding
• Configuratiehandleiding voor Nextcloud Office
• documentatie voor ingress-nginx-annotaties
• Helm install-opdrachtreferentie