Cómo configurar Collabora CODE en Kubernetes con Helm

Una página de Collabora Online puede permanecer en blanco o indicar que el servidor de Office no está disponible, incluso después de que el pod CODE esté en funcionamiento. Un pod en buen estado es solo una parte de la configuración: el navegador y su aplicación WOPI deben acceder a Collabora a través del nombre de host público, la configuración de TLS y del proxy deben coincidir, y Collabora debe confiar en el host WOPI. El gráfico Helm oficial de Collabora implementa el servidor en Kubernetes; no instala ni configura Nextcloud, ownCloud ni ningún otro host WOPI.

Esta guía utiliza el gráfico Helm mantenido por Collabora con un ejemplo de NGINX Ingress. Reemplace los dominios de ejemplo con los suyos. CODE es Collabora Online Development Edition, diseñada para evaluación, uso doméstico y equipos pequeños; Collabora indica que no se recomienda para entornos de producción que requieren una versión estable y con soporte. Para cargas de trabajo de producción, evalúe la oferta de Collabora Online compatible y sus términos de licencia y soporte.

Lo que necesitas antes de instalar

• Un clúster de Kubernetes en funcionamiento kubectly Helm 3 con acceso al clúster.
• Se ha instalado un controlador Ingress en el clúster. El ejemplo que se muestra a continuación utiliza ingress-nginx; el gráfico de Collabora también documenta HAProxy y admite otras configuraciones de enrutamiento.
• Un nombre DNS que office.example.comapunte a la dirección de entrada pública, además de un certificado TLS almacenado como un secreto de Kubernetes en el espacio de nombres de Collabora.
• Una aplicación WOPI como Nextcloud con una URL como cloud.example.com. Collabora debe poder acceder a la aplicación WOPI, y los navegadores de la aplicación y de los usuarios deben poder acceder a Collabora.
• Un plan TLS claro. Este ejemplo finaliza HTTPS en el punto de entrada y envía HTTP al servicio Collabora dentro del clúster.

Para una implementación rápida en casa o para pruebas, un único pod de CODE simplifica el enrutamiento. Varias réplicas pueden mejorar la capacidad, pero la guía de Kubernetes de Collabora destaca la necesidad de un balanceo de carga basado en WOPISrc para que las sesiones de edición del mismo documento lleguen al mismo pod. No escale las réplicas antes de confirmar que su controlador de entrada puede proporcionar la afinidad necesaria.

Paso 1: Añade la tabla oficial y selecciona una versión.

Collabora publica su gráfico desde el proyecto CollaboraOnline. La página de versiones actualmente muestra la versión 1.3.5 del gráfico (verificada el 6 de octubre de 2026). Inspeccione las versiones disponibles en su entorno y fije la versión del gráfico para que una actualización posterior del repositorio no modifique silenciosamente el gráfico que implementa.

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

El repositorio oficial de gráficos es útil para comprobar la configuración predeterminada actual antes de escribir modificaciones:

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

Si al seguir esta guía su repositorio muestra una versión compatible más reciente, revise sus notas de lanzamiento y valores antes de sustituirla. La versión de la tabla y la versión de la imagen de la aplicación CODE son parámetros de lanzamiento relacionados, pero no son la misma configuración.

Paso 2: Cree un espacio de nombres y proteja la contraseña de administrador.

Cree el espacio de nombres y un secreto de Kubernetes para las credenciales de administrador de Collabora opcionales del gráfico. Reemplace la contraseña de marcador de posición con un secreto seguro, o cree el secreto a través del administrador de secretos de su organización o el flujo de trabajo de secretos de GitOps. No confirme una contraseña real en 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'

El gráfico permite hacer referencia a un secreto existente. Habilitar esta opción evita tener que incluir la contraseña de administrador directamente en el archivo de valores de Helm. Mantenga el secreto restringido al espacio de nombres y a los usuarios o cuentas de servicio que administran esta implementación.

Paso 3: Configure el nombre de host, el host WOPI y el ingress.

Cree un archivo llamado collabora-values.yaml. Este ejemplo asume ingress-nginx, un secreto TLS llamado office-example-com-tlsy Nextcloud en https://cloud.example.com. El grupo de alias debe nombrar el host de la aplicación WOPI con el que Collabora tiene permiso para contactar; no es el nombre de host público de 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

El ejemplo documentado del gráfico permite aliasgroupsque el host WOPI utilice estos parámetros SSL cuando un proxy inverso finaliza TLS. En esta configuración, el tráfico externo office.example.comutiliza HTTPS, mientras que el ingress reenvía el tráfico a Collabora a través de HTTP dentro del clúster. Si su ingress utiliza TLS passthrough u otro protocolo interno, no copie estos indicadores SSL sin más; ajústelos para que coincidan con la ruta TLS real y los valores actuales del gráfico.

Confirme que el secreto TLS existe en el collaboraespacio de nombres. Si utiliza un controlador de entrada diferente, reemplace la clase y las anotaciones con los equivalentes documentados de dicho controlador. Mantenga habilitado el tráfico de websocket y permita conexiones de larga duración; la configuración predeterminada del controlador varía.

Paso 4: Renderizar e instalar el gráfico.

Primero, renderiza los manifiestos para detectar errores YAML y revisa la configuración generada de Ingress, Service y workload. Luego, instala la versión del gráfico fijada:

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

Observa los recursos a medida que se vayan publicando:

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

Espere a que el pod esté listo antes de conectar la aplicación WOPI. Si permanece pendiente, compruebe si el clúster dispone de suficiente CPU y memoria programables y si algún selector de nodos, restricción o cuota de recursos impide su asignación. El gráfico deja las solicitudes y los límites de recursos a elección del operador; el archivo README de Collabora proporciona ejemplos de valores de recursos mayores para entornos de producción, pero el dimensionamiento real depende de la edición concurrente y la carga de trabajo de los documentos.

Paso 5: Conecta Nextcloud u otro host WOPI.

Abra la configuración de Office o Collabora de su aplicación WOPI e ingrese la URL del servicio externo https://office.example.com. En Nextcloud, el manual de administración describe cómo configurar la URL del servidor de Collabora Online en la configuración de administración de Office. Verifique también la lista de permisos de solicitudes WOPI de Nextcloud si su configuración restringe los hosts que pueden conectarse. La dirección debe ser accesible tanto para los navegadores de los usuarios finales como para el servidor de la aplicación que realiza las solicitudes WOPI.

Si la conexión falla con un mensaje de "host WOPI no autorizado" o similar, compare la URL real del host WOPI con la de la aplicación collabora.aliasgroups. Verifique el esquema, el nombre de host y el puerto, y agregue deliberadamente cualquier nombre de host alternativo legítimo. Evite patrones de host amplios a menos que comprenda su efecto. Si utiliza más de una aplicación WOPI, siga la estructura de grupos de alias documentada en la tabla para cada host en lugar de permitir todos los dominios.

¿Cuándo conviene ampliar la escala más allá de un solo pod?

Para una prueba pequeña, una réplica con el escalado automático deshabilitado evita la complejidad del enrutamiento. Para múltiples réplicas, el archivo README del gráfico de Collabora muestra la afinidad de NGINX según el WOPISrcargumento de la consulta. Agregue la anotación documentada al ingress cuando utilice ingress-nginx:

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

Esto dirige las solicitudes del mismo documento al mismo pod de backend, lo cual es importante para la edición colaborativa y las solicitudes del portapapeles. Consulta la documentación para conocer la versión exacta de tu controlador de entrada; una anotación compatible con ingress-nginx no es automáticamente válida para HAProxy, Traefik o una implementación de la API de Gateway. Después de habilitar más réplicas o el escalado automático, prueba las ediciones simultáneas del mismo documento y observa los registros de Collabora y los registros de acceso de entrada. El dimensionamiento de recursos, el comportamiento de la sesión y la alta disponibilidad requieren una validación específica para cada carga de trabajo.

Verifique el despliegue desde el exterior.

1. Confirme que Kubernetes informa que el pod está listo y que el servicio y el Ingress existen: kubectl get pods,svc,ingress -n collabora.
2. Compruebe el punto final de descubrimiento público. Debería devolver XML en lugar de un error del navegador o del proxy:

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

3. Abra la aplicación WOPI y edite un documento de prueba. Compruebe que el editor se carga, que los cambios se guardan y que al volver a abrir el documento se muestra el contenido guardado.
4. Si utiliza varias réplicas, abra el mismo documento en dos sesiones y confirme que ambas pueden colaborar sin necesidad de reconexiones repetidas. Esto ayuda a identificar posibles problemas de afinidad entre las sesiones.
5. Revise los registros en busca de errores de TLS, autorización WOPI o errores de origen:

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

   Si el gráfico crea una carga de trabajo con un nombre diferente, utilice kubectl get deployments -n collaborael nombre real y sustitúyalo.

Una respuesta de detección exitosa confirma que el punto final público está proporcionando metadatos de Collabora; no prueba que la autenticación WOPI o el guardado de documentos funcionen. La prueba de documentos de extremo a extremo es la verificación final.

Puntos de fallo comunes

• Ingress devuelve 404 o 502: verifique el DNS, la clase de ingress, el secreto TLS y los puntos finales del servicio. Confirme que ingress puede acceder al servicio de Collabora en el puerto de servicio del gráfico.
• La función de detección funciona, pero el editor permanece en blanco: revise los errores de la consola del navegador y los registros del proxy. Compruebe la configuración de terminación HTTPS, el manejo de websockets y los tiempos de espera prolongados para las solicitudes.
• Host WOPI no autorizado: permita el origen de la aplicación WOPI en aliasgroups; no sustituya el nombre de host del servidor de oficina.
• Si un pod se reinicia o se elimina, inspeccione kubectl describe podlos registros del contenedor y, a continuación, establezca solicitudes y límites de recursos realistas para el clúster disponible.
• La edición se vuelve inestable después de agregar réplicas: verifique la afinidad basada en WOPISrc y confirme que el controlador conserva el argumento de consulta al enrutar las solicitudes.

Una vez instalado el gráfico, accesible el punto final de detección y abierto y guardado correctamente un documento real mediante la aplicación WOPI, la implementación principal de CODE funciona correctamente. Mantenga fija la versión del gráfico y repita estas comprobaciones tras las actualizaciones del gráfico, los cambios de entrada o los cambios de escalado.

Referencias oficiales

• Guía de implementación y gráficos Helm de Kubernetes mantenidos por Collabora
• Valores del gráfico de Collabora Helm
• Lanzamientos de listas de Collabora
• Guía de Collabora Online Development Edition (CODE)
• Manual de configuración de Nextcloud Office
• Documentación de anotaciones de ingress-nginx
• Referencia del comando de instalación de Helm