Kubernetes 노드에서 Collabora를 온라인으로 실행하세요

다중 노드 Collabora Online 배포의 경우, Collabora의 Kubernetes Helm 차트를 인그레스 또는 리버스 프록시 뒤에 배치하여 동일한 문서에 대한 모든 요청이 동일한 Collabora Pod에 유지되도록 해야 합니다. 이러한 세션 선호도는 필수적입니다. 일반적인 라운드 로빈 로드 밸런싱 방식은 사용자의 편집 및 클립보드 요청을 서로 다른 Pod로 전송하여 공동 편집을 방해할 수 있습니다. 아래 예제는 세 개의 복제본, NGINX 인그레스 및 고정된 복제본 수를 사용합니다. 예제의 호스트 이름과 TLS 시크릿은 사용자의 환경에 맞게 변경하십시오.

복제본을 추가하기 전에 무엇이 필요합니까?

실행 중인 Kubernetes 클러스터(최소 2개의 워커 노드 포함), Helm, 필요한 어피니티 규칙을 지원하는 인그레스 컨트롤러, DNS 이름(예: ` office.example.comNextcloud.com`) 및 해당 이름에 대한 TLS 인증서가 필요합니다. 각 Collabora Pod는 공용 WOPI 오리진(예: `Nextcloud.com`)을 통해 Nextcloud에 접근할 수 있어야 합니다 https://cloud.example.com. CODE와 Nextcloud는 별개의 서비스입니다. 이 가이드에서는 Collabora 계층을 구성한 다음 해당 공용 URL을 Nextcloud Office에 연결합니다.

여러 개의 독립적인 Docker 컨테이너를 일반 로드 밸런서 뒤에 배치하는 대신 Collabora 차트에 문서화된 다중 복제본 설정을 사용하십시오. 문서의 WOPI 소스를 고려하지 않고 각 요청을 분산하는 로드 밸런서는 세션을 중단시킬 수 있습니다. 이 가이드는 2026년 10월 10일에 제공된 공식 Collabora Helm 차트 지침을 따릅니다. 차트 값은 변경될 수 있으므로 설치하려는 정확한 차트 릴리스의 값을 확인하십시오.

1. 복제본, 인그레스 선호도 및 WOPI 호스트를 구성합니다.

차트 저장소를 추가하고, 인덱스를 업데이트하고, 차트의 현재 기본 설정을 확인한 후 재정의 파일을 작성하세요.

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

아래 핵심 설정으로 생성하세요 my_values.yaml. 이 샘플은 Collabora 차트 README에 나와 있는 NGINX Ingress 어노테이션을 사용합니다. WOPISrc요청이 하나의 문서와 연결되면 동일한 Pod에 도달하도록 해싱 기능을 활성화합니다. 또한, 인그레스에서 공용 TLS를 종료합니다. 여기에 표시된 Collabora 서버 설정은 프록시에서 종료되는 TLS 패턴에 맞춰져 있습니다.

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

입력 aliasgroups항목은 Collabora 호스트 이름이 아니라 Nextcloud WOPI 호스트입니다. Nextcloud에서 제공하는 정확한 스키마, 호스트 이름 및 포트를 사용하여 간결하게 작성하십시오. 인그레스 TLS 시크릿은 인그레스 네임스페이스에 존재해야 하며 유효한 인증서를 포함해야 합니다 office.example.com. TLS가 다른 곳에서 종료되는 경우, 두 플래그를 무턱대고 복사하는 대신 차트 문서에 있는 해당 프록시 패턴을 따르십시오 extra_params.

버전별로 자동 스케일링 관련 주의 사항이 있습니다. 차트 README의 샘플은 자동 스케일링을 비활성화하고 스케일링으로 인해 공동 편집 및 복사/붙여넣기 작업이 중단될 수 있다고 경고하는 반면, 현재 게시된 값 파일은 기본적으로 자동 스케일링이 활성화되어 있습니다. 예측 가능한 초기 클러스터 구성을 위해서는 자동 스케일링을 명시적으로 비활성화하고 고정된 복제본 수를 선택하는 것이 좋습니다. 정확한 차트 릴리스의 지침을 확인하고 실제 편집 세션을 통해 스케일 업 및 스케일 다운을 테스트한 후에만 자동 스케일링을 다시 검토하십시오.

2. 차트를 설치하고 포드 위치를 확인합니다.

차트를 지정된 네임스페이스에 설치하세요. 공식 차트 저장소에는 이 명령 패턴이 설명되어 있습니다.

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

그런 다음 배포가 원하는 복제본 수에 도달했는지 확인하고 어떤 워커 노드가 파드를 호스팅하는지 확인합니다.

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

세 개의 파드가 모두 준비 상태인지, 인그레스에 예상 호스트가 할당되었는지, 노드 수준의 복원력이 필요한 경우 복제본이 워커 노드에 분산되었는지 확인하십시오. 복제본 수만으로는 Kubernetes가 파드를 서로 다른 노드에 배치한다는 것을 보장할 수 없습니다. 공식 차트 템플릿은 노드 선택기, 선호도 및 허용 설정을 제공합니다. 클러스터에 적합한 스케줄링 규칙을 구성하고 렌더링된 차트를 검증한 후에 사용하십시오. 차트 릴리스에서 필요한 정책을 제공하지 않는 경우, 파드가 분산되어 있다고 가정하기보다는 지원되는 차트 확장 기능이나 Kubernetes 배포 사용자 정의를 사용하십시오.

3. Nextcloud에 연결하고 문서 친화성을 확인합니다.

Nextcloud에서 Nextcloud Office 앱을 설치하거나 활성화한 다음 관리 설정 → Office를 엽니다 . 외부 Collabora 서버를 선택하고 서버 URL을 입력합니다 https://office.example.com. 서버 URL은 Nextcloud 서버와 사용자 브라우저 모두에 접근 가능한 공개 TLS 엔드포인트입니다. Pod IP 주소나 내부 서비스 주소를 입력하지 마십시오.

Nextcloud에서 테스트용 DOCX 또는 ODT 파일을 엽니다. 두 개의 서로 다른 사용자 세션에서 파일을 편집하고 두 사용자 모두 변경 사항을 볼 수 있는지 확인합니다. 또한 브라우저 개발자 도구 또는 인그레스 로그에서 WebSocket 오류를 확인합니다. 인그레스는 장시간 편집기 연결을 계속 열어 두어야 합니다. 한 파일에 대한 요청이 여러 파드에 분산되어 있는 경우, WOPISrc인그레스가 해시 규칙을 적용하는 부분에 쿼리 매개변수가 있는지, 그리고 설치된 인그레스 컨트롤러가 어노테이션을 준수하는지 확인합니다.

건강한 클러스터는 무엇을 증명하는가?

테스트가 성공하면 Nextcloud가 Collabora 엔드포인트에 연결할 수 있고 구성된 인그레스를 통해 문서를 편집할 수 있음을 확인하는 것입니다. 하지만 모든 활성 세션이 Pod 또는 노드 장애 발생 시에도 유지된다는 것을 보장하는 것은 아닙니다. 편집 상태는 해당 문서를 제공하는 Pod에서 관리되므로, 장애 발생 시 다른 복제본이 사용 가능한 상태이더라도 사용자는 다시 연결하거나 파일을 다시 열어야 할 수 있습니다. 중요하지 않은 문서를 사용하여 유지 관리 및 장애 시나리오를 테스트하고, 장기 WebSocket 세션을 신중하게 처리할 수 있도록 업그레이드 계획을 수립하십시오.

최신 구문 및 주의 사항은 Collabora의 공식 Kubernetes Helm 차트 README 및 값 파일 , 게시된 차트 값 파일 , 그리고 Nextcloud의 Office 구성 설명서를 참조하십시오 . 저장소의 예제 및 기본값이 설치한 차트 버전과 다를 수 있으므로 설치한 차트 버전에 맞춰 설정을 확인하십시오.