Helm을 사용하여 Kubernetes에 Collabora CODE를 설정하는 방법

Collabora Online 페이지가 비어 있거나 CODE pod가 실행 중인 후에도 오피스 서버를 사용할 수 없다는 메시지가 표시될 수 있습니다. pod가 정상적으로 실행되는 것만으로는 설정의 일부일 뿐입니다. 브라우저와 WOPI 애플리케이션이 공용 호스트 이름을 통해 Collabora에 연결되어야 하고, TLS 및 프록시 설정이 일치해야 하며, Collabora가 WOPI 호스트를 신뢰해야 합니다. 공식 Collabora Helm 차트는 서버를 Kubernetes에 배포하는 역할을 하며, Nextcloud, ownCloud 또는 다른 WOPI 호스트를 설치하거나 구성하지는 않습니다.

이 가이드에서는 Collabora에서 제공하는 Helm 차트와 NGINX Ingress 예제를 사용합니다. 샘플 도메인은 실제 도메인으로 교체하십시오. CODE는 Collabora Online 개발 에디션으로, 평가, 개인 용도 및 소규모 팀을 위해 설계되었습니다. Collabora는 안정적인 지원 릴리스가 필요한 프로덕션 환경에는 CODE 사용을 권장하지 않습니다. 프로덕션 워크로드의 경우, 지원되는 Collabora Online 제품과 해당 라이선스 및 지원 조건을 검토하십시오.

설치하기 전에 필요한 사항

• 정상적으로 작동하는 Kubernetes 클러스터 kubectl와 해당 클러스터에 접근 가능한 Helm 3가 필요합니다.
• 클러스터에 설치된 Ingress 컨트롤러입니다. 아래 예시에서는 ingress-nginx를 사용하지만, Collabora 차트에는 HAProxy에 대한 설명과 다른 라우팅 구성도 포함되어 있습니다.
• 공용 인그레스 주소를 가리키는 DNS 이름 office.example.com과 Collabora 네임스페이스에 Kubernetes Secret으로 저장된 TLS 인증서가 필요합니다.
• Nextcloud와 같은 URL을 가진 WOPI 애플리케이션이 있어야 cloud.example.com합니다. Collabora는 해당 WOPI 애플리케이션에 접근할 수 있어야 하며, 애플리케이션과 사용자의 브라우저 또한 Collabora에 접근할 수 있어야 합니다.
• 명확한 TLS 계획. 이 예시에서는 HTTPS를 진입점에서 종료하고 클러스터 내부의 Collabora 서비스로 HTTP를 전송합니다.

빠른 가정 환경 또는 테스트 배포의 경우, 단일 CODE Pod를 사용하면 라우팅이 간단해집니다. 여러 복제본을 사용하면 용량을 향상시킬 수 있지만, Collabora의 Kubernetes 가이드에서는 동일한 문서에 대한 편집 세션이 동일한 Pod에 도달하도록 WOPISrc 기반 로드 밸런싱이 필요하다고 명시하고 있습니다. 인그레스 컨트롤러가 필요한 어피니티를 제공할 수 있는지 확인하기 전에는 복제본을 확장하지 마십시오.

1단계: 공식 차트를 추가하고 버전을 선택하세요.

Collabora는 CollaboraOnline 프로젝트에서 차트를 게시합니다. 현재 릴리스 페이지에는 차트 버전 1.3.5가 표시되어 있습니다(2026년 10월 6일 확인). 사용 환경에서 사용 가능한 버전을 확인하고 차트 버전을 고정하여 나중에 저장소가 업데이트되더라도 배포하는 차트가 자동으로 변경되지 않도록 하십시오.

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 --version 1.3.5

이 가이드를 따랐을 때 저장소에 더 최신 버전의 호환 차트가 있는 경우, 해당 버전으로 교체하기 전에 릴리스 노트와 값을 검토하십시오. 차트 버전과 CODE 애플리케이션 이미지 버전은 관련 릴리스 입력값이지만 동일한 설정은 아닙니다.

2단계: 네임스페이스를 생성하고 관리자 암호를 보호합니다.

차트의 선택적 Collabora 관리자 자격 증명을 위한 네임스페이스와 Kubernetes Secret을 생성합니다. 자리 표시자 암호를 강력한 암호로 바꾸거나, 조직의 Secret 관리자 또는 GitOps Secret 워크플로를 통해 Secret을 생성하세요. 실제 암호를 커밋하지 마세요 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'

이 차트는 기존 Secret을 참조하는 기능을 지원합니다. 이 기능을 활성화하면 관리자 암호를 Helm 값 파일에 직접 입력하지 않아도 됩니다. Secret은 해당 배포를 관리하는 네임스페이스 및 사용자 또는 서비스 계정으로 제한하여 관리하십시오.

3단계: 호스트 이름, WOPI 호스트 및 인그레스를 구성합니다.

라는 이름의 파일을 생성합니다 collabora-values.yaml. 이 예제에서는 ingress-nginx, 라는 이름의 TLS Secret office-example-com-tls, 그리고 의 Nextcloud를 가정합니다 https://cloud.example.com. 별칭 그룹은 Collabora가 통신할 수 있도록 허용된 WOPI 애플리케이션 호스트의 이름을 지정해야 하며, 공개 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

차트의 예제에서는 aliasgroups리버스 프록시가 TLS를 종료할 때 WOPI 호스트와 이러한 SSL 매개변수를 허용하도록 설정되어 있습니다. 이 구성에서는 외부 트래픽은 office.example.comHTTPS를 사용하고, 인그레스는 클러스터 내부의 Collabora로 HTTP를 통해 트래픽을 전달합니다. 인그레스가 TLS 패스스루 또는 다른 내부 프로토콜을 사용하는 경우, 이러한 SSL 플래그를 그대로 복사하지 말고 실제 TLS 경로 및 차트의 현재 값에 맞게 조정해야 합니다.

TLS 시크릿이 collabora네임스페이스에 존재하는지 확인하십시오. 다른 인그레스 컨트롤러를 사용하는 경우, 해당 컨트롤러의 문서에 나와 있는 클래스와 어노테이션으로 교체하십시오. 웹소켓 트래픽을 활성화하고 장기 연결을 허용하십시오. 컨트롤러별 기본 설정은 다를 수 있습니다.

4단계: 차트를 렌더링하고 설치합니다.

먼저 매니페스트를 렌더링하여 YAML 오류를 확인하고 생성된 Ingress, Service 및 워크로드 설정을 검토합니다. 그런 다음 고정된 차트 릴리스를 설치합니다.

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

자료들이 시작될 때를 지켜보세요:

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

WOPI 애플리케이션을 연결하기 전에 Pod가 Ready 상태가 될 때까지 기다리십시오. Pod가 Pending 상태로 유지되면 클러스터에 스케줄링 가능한 CPU와 메모리가 충분한지, 그리고 노드 선택기, 테인트 또는 리소스 할당량으로 인해 배치가 불가능한지 확인하십시오. 차트는 운영자가 선택할 수 있도록 리소스 요청 및 제한 값을 제공합니다. Collabora의 README에는 프로덕션 환경에 적합한 더 큰 리소스 값 예시가 나와 있지만, 실제 크기 조정은 동시 편집 및 문서 작업 부하에 따라 달라집니다.

5단계: Nextcloud 또는 다른 WOPI 호스트에 연결합니다.

WOPI 애플리케이션의 Office 또는 Collabora 설정을 열고 외부 서비스 URL을 입력하십시오 https://office.example.com. Nextcloud의 경우 관리 설명서에서 Office 관리 설정에서 Collabora Online 서버의 URL을 설정하는 방법을 설명합니다. 또한 설정에 따라 연결할 수 있는 호스트가 제한되어 있는 경우 Nextcloud WOPI 요청 허용 목록을 확인하십시오. 해당 주소는 최종 사용자 브라우저와 WOPI 요청을 수행하는 애플리케이션 서버 모두에서 접근 가능해야 합니다.

"권한 없는 WOPI 호스트" 또는 유사한 메시지와 함께 연결이 실패하면 실제 WOPI 호스트 URL을 다음 URL과 비교하십시오 collabora.aliasgroups. 스키마, 호스트 이름 및 포트를 확인하고, 유효한 대체 호스트 이름을 의도적으로 추가하십시오. 영향을 이해하지 못하는 한 광범위한 호스트 패턴은 사용하지 마십시오. 두 개 이상의 WOPI 애플리케이션을 사용하는 경우 모든 도메인을 허용하는 대신 각 호스트에 대해 차트에 문서화된 별칭 그룹 구조를 따르십시오.

언제 포드를 하나 이상 확장해야 할까요?

소규모 테스트의 경우, 자동 확장이 비활성화된 단일 복제본을 사용하면 라우팅 복잡성을 줄일 수 있습니다. 여러 복제본의 경우, Collabora 차트 README에서 WOPISrc쿼리 인수에 따른 NGINX 선호도를 확인할 수 있습니다. ingress-nginx를 사용할 때는 문서에 설명된 어노테이션을 인그레스에 추가하세요.

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

이는 동일한 문서에 대한 요청을 동일한 백엔드 Pod로 전달하므로 공동 편집 및 클립보드 요청에 중요합니다. 사용 중인 ingress-controller 버전에 맞는 문서를 확인하세요. ingress-nginx에서 지원하는 어노테이션이 HAProxy, Traefik 또는 Gateway API 구현에서 자동으로 유효한 것은 아닙니다. 복제본 수를 늘리거나 자동 스케일링을 활성화한 후, 동일한 문서에 대한 동시 편집을 테스트하고 Collabora 로그와 ingress 액세스 로그를 확인하세요. 리소스 크기 조정, 세션 동작 및 고가용성은 워크로드별로 검증해야 합니다.

외부에서 배포 상태를 확인하세요

1. Kubernetes가 파드를 준비 상태로 보고하고 서비스와 인그레스가 존재하는지 확인하십시오 kubectl get pods,svc,ingress -n collabora.
2. 공개 검색 엔드포인트를 확인하십시오. 브라우저 또는 프록시 오류가 아닌 XML이 반환되어야 합니다.

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

3. WOPI 애플리케이션을 열고 테스트 문서를 편집합니다. 편집기가 제대로 로드되고, 변경 사항이 저장되며, 문서를 다시 열었을 때 저장된 내용이 표시되는지 확인합니다.
4. 여러 복제본을 사용하는 경우, 두 세션에서 동일한 문서를 열고 재연결 없이 두 세션 모두 공동 작업이 가능한지 확인하십시오. 이렇게 하면 세션 연결 문제가 발생하는 원인을 파악하는 데 도움이 됩니다.
5. TLS, WOPI 인증 또는 업스트림 오류에 대한 로그를 검토하십시오.

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

   차트에서 다른 이름의 작업 부하가 생성되는 경우 kubectl get deployments -n collabora실제 이름을 사용하고 대체하십시오.

검색 응답이 성공적이면 공용 엔드포인트가 Collabora 메타데이터를 제공하고 있음을 확인하는 것이지만, WOPI 인증이나 문서 저장이 제대로 작동한다는 것을 증명하는 것은 아닙니다. 최종 확인은 엔드투엔드 문서 테스트입니다.

일반적인 실패 요인

• Ingress에서 404 또는 502 오류가 발생하는 경우 DNS, Ingress 클래스, TLS Secret 및 서비스 엔드포인트를 확인하십시오. Ingress가 차트의 서비스 포트를 통해 Collabora 서비스에 연결할 수 있는지 확인하십시오.
• 검색은 되지만 편집기 화면이 비어 있는 경우: 브라우저 콘솔 오류 및 프록시 로그를 확인하십시오. HTTPS 종료 설정, 웹소켓 처리 및 요청 시간 초과 문제를 점검하십시오.
• 승인되지 않은 WOPI 호스트: WOPI 애플리케이션의 출처를 허용하십시오 aliasgroups. 사무실 서버 호스트 이름을 바꾸지 마십시오.
• Pod가 재시작되거나 제거된 경우: 컨테이너 로그를 검사하고 kubectl describe pod, 사용 가능한 클러스터에 맞는 현실적인 리소스 요청 및 제한을 설정하십시오.
• 복제본을 추가한 후 편집이 불안정해집니다. WOPISrc 기반 선호도를 확인하고 컨트롤러가 요청을 라우팅할 때 쿼리 인수를 유지하는지 확인하십시오.

차트가 설치되고, 검색 엔드포인트에 접근할 수 있으며, WOPI 애플리케이션을 통해 실제 문서가 성공적으로 열리고 저장되면 핵심 CODE 배포가 정상적으로 작동하는 것입니다. 차트 버전을 고정해 두고, 차트 업그레이드, 인그레스 변경 또는 스케일링 변경 후에는 이러한 검사를 반복하십시오.

공식 참고 자료

• Collabora에서 관리하는 Kubernetes Helm 차트 및 배포 가이드
• Collabora Helm 차트 값
• Collabora 차트 출시
• Collabora 온라인 개발 에디션(CODE) 사용 설명서
• Nextcloud Office 구성 설명서
• ingress-nginx 어노테이션 문서
• Helm 설치 명령 참조