Comment configurer un cluster Collabora Online avec plusieurs nœuds

Un cluster Collabora Online ne se résume pas à plusieurs coolwsdserveurs fonctionnels derrière un répartiteur de charge à répartition circulaire. L'édition collaborative repose sur l'envoi des requêtes relatives à un même document vers le même nœud Collabora. WOPISrcC'est pourquoi le graphique Kubernetes de Collabora documente le routage par identifiant WOPI. Ce guide utilise le graphique Helm Collabora maintenu sur Kubernetes comme exemple concret de configuration multi-nœuds et indique les modifications nécessaires pour un contrôleur d'entrée différent ou un déploiement hors Kubernetes.

Vérifié : le graphique de Collabora prend en charge plusieurs réplicas et décrit l’affinité par document WOPISrc. Dépend du déploiement : annotations d’entrée, terminaison TLS, requêtes de ressources et pertinence d’un contrôleur de session. Attention : il est déconseillé de supposer que tout équilibreur de charge ou paramètre de « session persistante » préservera l’affinité des documents. Vérifiez le comportement spécifique du contrôleur et testez-le avant de déployer les utilisateurs sur le cluster.

Ce que fait le cluster — et ce qu'il ne fait pas

Dans un déploiement multi-répliques standard, chaque nœud Collabora peut servir des documents, tandis qu'un proxy achemine les requêtes de chaque document vers un nœud. Cela répartit les documents entre les différents nœuds. Cela ne signifie pas pour autant que chaque nœud partage le même processus d'édition en direct ni qu'un document en cours d'édition peut toujours être transféré sans interruption si son nœud tombe en panne.

Collabora documente également un contrôleur COOL pour Kubernetes qui propose une approche différente de la gestion des sessions. Son routage et sa configuration diffèrent de ceux d'un pool de réplicas autonome. Cet article configure le modèle d'affinité WOPI, plus simple ; ne le combinez pas avec les paramètres de jeton de routage spécifiques au contrôleur, sauf si vous avez déployé et configuré ce dernier pour votre version.

Action : déterminez si vous avez besoin d’un service Collabora répliqué de base pour la capacité et la redondance des nœuds, ou d’une configuration gérée par un contrôleur avec prise en charge des sessions. Cette dernière comprend des composants supplémentaires et une configuration spécifique à la version. Consultez la présentation de Collabora Online Controller si vous envisagez cette option.

Avant de déployer

• Un cluster Kubernetes fonctionnel, Helm, un DNS pour un nom d'hôte Collabora public et un proxy d'entrée ou inverse compatible TLS.
• Une intégration WOPI telle que Nextcloud, configurée pour utiliser le nom d'hôte public unique de Collabora plutôt que des adresses de pods individuelles.
• L'hôte ou les hôtes WOPI que Collabora est autorisé à accepter, saisis dans la collabora.aliasgroupsconfiguration du graphique.
• Une puissance de calcul et une mémoire suffisantes pour la charge de travail liée aux documents, ainsi qu'un moyen d'inspecter l'état des pods, les journaux d'entrée et l'utilisation des ressources.
• Une fenêtre de maintenance pour le déploiement initial et un document de test avec deux comptes utilisateurs distincts.

Un service Collabora Online dédié est différent du serveur CODE intégré de Nextcloud. Nextcloud décrit son option intégrée comme étant destinée à un usage personnel ou aux petites équipes et ne proposant pas les fonctionnalités de scalabilité avancées d'un serveur dédié. Action : si vous avez besoin d'un pool Collabora multi-nœuds, prévoyez un service dédié et vérifiez le modèle de licence et de support adapté à votre déploiement. Consultez le guide d'installation de Nextcloud Office .

Étape 1 : Choisir le modèle de routage

Le modèle autonome documenté utilise un hachage WOPISrcqui identifie le document dans les requêtes WOPI. Les requêtes concernant un même document doivent parvenir au même pod ; les requêtes concernant des documents différents peuvent être réparties entre plusieurs pods. Une règle de répartition de charge générique ne répond pas à cette exigence.

Action : utilisez une implémentation d’entrée prise en charge par la documentation du graphique, comme les exemples d’entrée NGINX ou HAProxy, ou utilisez le proxy inverse intégré au graphique si le cluster ne prend pas en charge un contrôleur d’entrée approprié. Si vous utilisez un autre proxy, vérifiez qu’il peut acheminer de manière cohérente les requêtes provenant de la source WOPI, aussi bien les requêtes HTTP classiques que les connexions WebSocket persistantes.

Étape 2 : Examinez le graphique et sélectionnez une version

Le graphique et ses valeurs évoluent avec le temps. Avant l'installation, consultez le fichier README et les valeurs officielles actuelles du graphique plutôt que de copier une configuration d'une version antérieure. Les exemples ci-dessous suivent la documentation du graphique Collabora mise à jour le 6 octobre 2026 ; considérez les notes de version et les valeurs actuelles du dépôt comme faisant foi pour votre installation.

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

Action : choisissez une version de graphique conforme à votre politique de gestion des changements et notez la version de l’image Collabora qu’elle déploie. Épinglez la version du graphique pour des mises à niveau reproductibles ; évitez d’utiliser une version flottante non validée en production. Le guide d’installation du graphique est le fichier README de Collabora Online pour Kubernetes .

Étape 3 : Préparer les valeurs pour trois répliques

Cet exemple suppose l'utilisation du contrôleur d'entrée NGINX, la terminaison TLS au niveau de l'entrée et un hôte WOPI externe cloud.example.com. Remplacez les deux noms d'hôte par les vôtres. Si la terminaison TLS se fait ailleurs ou si vous utilisez HAProxy, veuillez utiliser la configuration documentée correspondante de ce contrôleur.

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

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

Les valeurs d'annotation de hachage et de délai d'expiration ci-dessus sont illustrées dans l'exemple NGINX du graphique. Cette extra_paramsligne est pertinente uniquement lorsque le proxy inverse termine la connexion TLS et se connecte à Collabora via HTTP. Ne l'appliquez pas telle quelle si votre topologie TLS est différente. Configurez le secret TLS d'entrée et l'hôte en fonction de votre gestionnaire de certificats et des valeurs de votre graphique local ; cet extrait omet ces paramètres spécifiques au fournisseur.

Action : enregistrez ce fichier my_values.yaml, ajoutez la configuration TLS requise par votre point d’entrée et comparez chaque clé avec celle de la version du graphique sélectionnée values.yaml. Assurez-vous que le nom d’hôte public de Collabora soit cohérent dans le DNS, le TLS, l’URL Collabora de l’intégration et le routage proxy.

Étape 4 : Installez la version Collabora

Installez-le dans un espace de noms dédié. Remplacez-le <chart-version>par la version sélectionnée à l'étape 2 ; les chevrons servent ici d'espace réservé explicatif et ne doivent pas être saisis littéralement.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

Pour une version existante, utilisez une mise à niveau Helm planifiée après avoir consulté les notes de migration et les modifications rendues. Évitez de déployer une image ou une mise à jour majeure de graphique en même temps que votre première modification d'échelle ; modifier une seule variable à la fois facilite l'isolement des erreurs.

Action : inspecter la version et attendre que toutes les répliques soient prêtes :

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

La présence de trois réplicas souhaités ne garantit pas que trois nœuds opérationnels traitent le trafic. Vérifiez l'état de disponibilité, les redémarrages récents, la planification et les points de terminaison d'entrée. Si des pods restent en attente, examinez la capacité disponible du cluster ainsi que les demandes et les limites de ressources affichées dans le graphique.

Étape 5 : Connectez l’application WOPI

Dans les paramètres d'intégration Office de la plateforme de fichiers, définissez l'URL du serveur Collabora sur le point de terminaison public, par exemple : `http:// https://office.example.comlocalhost:8080`. Ne configurez pas l'application pour qu'elle utilise l'adresse IP d'un pod ou un nom de service Kubernetes, sauf si l'intégration elle-même s'exécute au sein du cluster et que ce routage privé est explicitement pris en charge par votre architecture.

Le nom d'hôte aliasgroupsdoit identifier l'hôte WOPI qui stocke et distribue les documents ; il ne s'agit pas du nom d'hôte Collabora. Une incohérence peut entraîner des échecs de validation de l'hôte WOPI même si les pods et l'ingress Collabora fonctionnent correctement.

Action : saisissez la même URL publique Collabora dans la configuration de l’intégration, enregistrez-la et vérifiez que la connexion ou la découverte réussit. En cas d’échec, vérifiez la liste blanche WOPI de l’application, les groupes d’alias Collabora, le DNS, le TLS et les en-têtes de proxy avant de modifier le nombre de réplicas.

Étape 6 : Tester l’affinité et la collaboration entre les documents

Ouvrez un document de test et examinez les journaux d'entrée ou de proxy pour confirmer quel serveur le traite. Ouvrez ensuite ce même document depuis une seconde session utilisateur et vérifiez que les deux utilisateurs peuvent le modifier et voir les modifications de l'autre. Ouvrez un autre document et vérifiez que l'équilibreur de charge peut l'envoyer à un autre pod opérationnel. Ce test porte sur le routage et la collaboration, et non pas uniquement sur le fait que la page d'accueil renvoie un code HTTP 200.

Action : vérifiez que le hachage source WOPI est présent et appliqué de manière cohérente aux requêtes générées pour un même document, y compris lors de la mise à niveau WebSocket. Si les utilisateurs ne voient pas les modifications des autres, comparez la sélection du serveur de stockage pour un même document avant d’examiner le serveur WOPI ou le cache du navigateur.

Étape 7 : Tester la gestion de l’état et la perte de nœuds

Les contrôles de disponibilité doivent empêcher l'accès au service d'un pod défaillant ou en cours de démarrage. Le graphique inclut les paramètres de démarrage, de disponibilité et de surveillance de la disponibilité, mais le comportement et le délai exacts dépendent de la version du graphique et du cluster sélectionnés. L'indisponibilité d'un pod peut interrompre l'exécution des documents en cours sur ce pod ; un pool d'affinité de base ne doit pas être décrit comme une réplication de session en direct.

Action : dans un environnement de test, retirez un pod du service pendant une session d’édition active, observez le comportement du client et le routage du proxy, puis rouvrez le document et vérifiez qu’il atteint un pod opérationnel. N’effectuez pas ce test sur des documents de production actifs sans plan de maintenance approuvé. Pour une continuité de session plus stricte, évaluez le contrôleur COOL et sa configuration de jeton de routage spécifique à la version.

Étape 8 : Surveiller, régler et mettre à niveau de manière délibérée

Suivez les redémarrages des pods, l'utilisation du processeur et de la mémoire, les erreurs de requêtes et de WebSocket, la latence d'entrée et les rapports des utilisateurs concernant le chargement des documents ou les reconnexions. La documentation des graphiques de Collabora inclut des conseils de surveillance Kubernetes. Configurez les ressources en fonction de la charge de travail observée plutôt que de copier des exemples : la taille des documents, les sessions simultanées, les polices et les habitudes d'édition ont tous une incidence sur la capacité.

Collabora recommande d'exécuter la même version sur tous les nœuds à charge équilibrée afin que les clients reçoivent des ressources web cohérentes et spécifiques à la version. Lors des mises à niveau, utilisez la stratégie de déploiement recommandée, surveillez l'état de préparation et les journaux, et testez l'ouverture d'un document par plusieurs utilisateurs avant de déclarer la modification terminée.

Action : conservez la version du graphique, la version de l’image, le fichier de valeurs et les résultats des tests dans votre enregistrement des modifications. Planifiez les mises à niveau, vérifiez que toutes les répliques convergent vers la version cible et prévoyez un plan de restauration compatible avec le comportement de restauration pris en charge par le graphique.

Idées fausses courantes à vérifier

• « Trois réplicas créent automatiquement un cluster fonctionnel. » Les réplicas seuls ne configurent pas l’affinité des documents. Vérifiez que les hachages d’entrée sont corrects sur la source WOPI ou que votre contrôleur assure le routage de session prévu.
• « Les sessions persistantes basées sur l'adresse IP d'un utilisateur suffisent. » Ce n'est pas la règle décrite par le graphique de Collabora pour son pool Kubernetes autonome. Les utilisateurs collaborant sur un même document doivent se connecter au même nœud, même s'ils utilisent des appareils ou des réseaux différents. Configurez l'affinité basée sur les documents et effectuez un test avec deux utilisateurs.
• « Une page d'accueil fonctionnelle prouve que le cluster est prêt. » Cela prouve seulement qu'une requête HTTP a abouti. Testez l'ouverture et la modification collaborative d'un document, les mises à jour WebSocket et le comportement lorsqu'un pod devient indisponible.
• L’ajout d’un nœud garantit la continuité des sessions actives en cas de perte de nœud. Un pool d’affinité de source WOPI basique achemine un document vers un nœud ; il n’assure pas la réplication de son processus d’édition en mémoire. Vérifiez le comportement attendu en cas de reprise d’activité lors d’un test contrôlé ou évaluez les fonctionnalités de gestion de session du contrôleur.

Pour les installations non-Kubernetes, le principe d'architecture reste le même, mais les commandes des charts Kubernetes et les annotations d'entrée ne s'appliquent pas. Utilisez la configuration de proxy correspondant à votre version de Collabora et à votre équilibreur de charge, assurez-vous que les connexions WebSocket persistantes sont prises en charge et implémentez le routage par document à l'aide de la source WOPI. Le manuel du SDK Collabora Online décrit l'équilibrage de charge et les WOPISrcexigences d'affinité ; consultez la section correspondante du manuel de la version que vous utilisez.