Helm을 사용하여 Kubernetes에 Collabora CODE 배포하기

2026년 10월 10일 현재, 업스트림 패키지 레지스트리에는 차트 버전 1.3.0이 최신 릴리스로 등록되어 있습니다. 차트 설치는 정상적인 배포를 위한 일부일 뿐입니다. 공개된 Collabora 호스트 이름, 문서 저장소 호스트에 대한 유효한 WOPI 허용 목록 항목, 그리고 각 문서에 대한 요청을 동일한 Pod에서 처리하는 인그레스 설정도 필요합니다. 업스트림 패키지 레지스트리에는 작성 시점을 기준으로 차트 버전 1.3.0이 등록되어 있습니다. Helm 차트 버전과 CODE 컨테이너 이미지 버전은 별개의 값이므로 설치 전에 저장소를 확인하십시오.

이 절차에서는 공식 collabora/collabora-online차트와 NGINX Ingress Controller를 사용합니다. 차트 README에는 HAProxy 예제도 포함되어 있습니다. Ingress 어노테이션은 컨트롤러별로 다르므로, 여러 어노테이션을 혼합하여 사용하지 말고 설치된 컨트롤러에 맞는 예제를 사용하십시오.

무엇을 먼저 준비해야 할까요?

• 네임스페이스, Deployment, Service 및 Ingress를 생성할 수 있는 권한이 있는 Kubernetes 클러스터입니다.
• Helm 3와 .와 같은 호스트 이름에 대해 HTTPS를 제공할 수 있는 설치된 인그레스 컨트롤러가 필요합니다 office.example.com.
• Nextcloud 또는 Seafile과 같은 WOPI 클라이언트의 공개 호스트 이름입니다. 이는 Collabora에서 허용해야 하는 호스트이며, Collabora 자체의 호스트 이름이 아닙니다.
• Collabora 관리 콘솔 자격 증명을 위한 Kubernetes Secret입니다. 차트 예제 암호를 저장하거나 실제 암호를 values ​​파일에 저장하지 마십시오.

1. 공식 차트 저장소를 추가하고 릴리스를 확인하세요.

Collabora는 프로젝트의 온라인 저장소에서 차트를 게시합니다. 설치하기 전에 차트를 추가하고 로컬 인덱스를 새로 고친 다음 차트 메타데이터와 기본값을 확인하십시오.

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

차트 버전은 패키지를 식별하는 데 사용되며, 반드시 CODE 이미지 태그를 식별하는 것은 아닙니다. 릴리스 값에서 이미지 저장소와 태그를 확인한 다음, 검토한 차트 버전을 고정하여 반복적인 업그레이드를 진행하세요.

승인된 시크릿 관리 워크플로를 사용하여 네임스페이스 범위의 시크릿을 생성하세요. 차트 값은 기존 시크릿과 구성 가능한 키 이름을 지원하며, 기본 키 이름은 username와 입니다 password. 설치하기 전에 네임스페이스에 시크릿이 있는지 확인하세요 collabora.

2. WOPI 호스트, 인그레스 및 프록시 옵션을 설정합니다.

생성하세요 my_values.yaml. 예시 호스트 이름 두 개를 실제 공개 도메인으로 바꾸세요. 첫 번째 aliasgroups값은 WOPI 클라이언트(예: Seafile 또는 Nextcloud 서버)를 식별합니다. 두 번째 값은 server_name사용자의 브라우저가 접속하는 Collabora 서비스를 식별합니다.

replicaCount: 1

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

autoscaling:
  enabled: false

collabora:
  aliasgroups:
    - host: "https://files.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true
  server_name: office.example.com:443
  existingSecret:
    enabled: true
    secretName: collabora-admin
    usernameKey: username
    passwordKey: password

이 예제는 Collabora에서 제공하는 NGINX 인그레스 패턴을 따릅니다. 요청은 매개변수를 사용하여 해시 처리되며 WOPISrc, 문서 세션의 경우 프록시 읽기 및 전송 시간 초과가 연장됩니다. 인그레스 컨트롤러 버전에 따라 어노테이션 이름을 확인하십시오. HAProxy를 사용하는 경우 차트 README의 HAProxy 어노테이션 및 로드 밸런싱 구성을 사용하십시오.

ssl.enable=false`--TLS` 및 `--HTTPS` 옵션 ssl.termination=true은 TLS가 인그레스에서 종료되고 인그레스에서 파드로 가는 트래픽이 내부적으로 처리되는 설계를 위한 것입니다. 이는 공용 엔드포인트에서 HTTP를 사용해야 한다는 의미가 아닙니다. 인그레스 호스트 이름은 HTTPS로 유지하고, 파드의 일반 HTTP 서비스를 인터넷에 직접 노출하지 마십시오. server_nameCollabora가 리버스 프록시 뒤에 있거나 외부 호스트 이름을 직접 추론할 수 없는 경우에 이 옵션을 설정하십시오.

고정 복제본이 여러 개인 경우, replicaCount의도적으로 설정하고 세션 선호도를 유지하십시오. 현재 업스트림 README에는 확장이 공동 편집 및 복사/붙여넣기에 지장을 줄 수 있으므로 HPA가 비활성화되어 있다고 명시되어 있습니다. 복제본 수를 늘리는 것만으로는 올바른 라우팅이 보장되지 않습니다. 인그레스가 동일한 문서에 대한 요청을 동일한 파드로 보내는지 확인하십시오.

3. Collabora CODE를 설치하세요

공식 저장소에서 릴리스 버전을 설치하고 배포 준비가 완료될 때까지 기다리세요.

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

kubectl get pods -n collabora
kubectl get ingress -n collabora

기존 릴리스를 업데이트하는 경우, helm upgrade두 번째 릴리스를 생성하는 대신 동일한 릴리스 이름, 네임스페이스 및 값 파일을 사용하십시오. 프로덕션 인스턴스를 업그레이드하기 전에 차트의 릴리스 노트와 렌더링된 변경 사항을 검토하십시오.

Pod가 준비되었는지, Ingress에서 예상 호스트와 주소가 보고되는지 확인하십시오. 만약 여전히 보류 중이라면, 리소스 설정을 변경하기 전에 이벤트와 로그를 검사하십시오.

kubectl describe pods -n collabora
kubectl logs -n collabora deployment/<deployment-name>

워크로드와 클러스터 용량에 맞춰 CPU와 메모리 크기를 조정하세요. 차트의 README 파일은 예시 요청 및 제한 사항을 제공하며, 모든 배포 환경에 적용되는 것은 아닙니다. 스로틀링, 메모리 부족으로 인한 종료 및 재시작에 주의하십시오.

4. 발견 사항 및 문서 편집 내용을 검증합니다.

DNS와 TLS가 활성화되면 공개 호스트 이름을 통해 Collabora의 검색 엔드포인트에 요청하십시오.

curl -fsS https://office.example.com/hosting/discovery

성공적인 응답에는 수신 오류 페이지나 인증서 경고 대신 WOPI 검색 XML이 포함되어야 합니다. 그런 다음 WOPI 클라이언트를 동일한 Collabora 공개 URL로 구성하고 Collabora에 aliasgroups해당 클라이언트의 HTTPS 호스트 이름과 포트가 포함되어 있는지 확인하십시오. 클라이언트의 정확한 설정은 스토리지 제품에 따라 다릅니다.

WOPI 클라이언트에서 테스트 문서를 열고 간단한 변경을 해보세요. 편집기가 제대로 로드되는지, 공동 작업이 필요한 경우 두 번째 브라우저 세션이 참여할 수 있는지, 그리고 변경 사항이 스토리지 서비스에 저장되는지 확인합니다. 이 엔드투엔드 점검은 DNS, 인그레스 TLS, 세션 라우팅, WOPI 호스트 인증 및 파일 전송 기능을 테스트합니다.

확인해야 할 일반적인 가정 사항

• "Helm이 설치되었으므로 Collabora는 프로덕션 환경에서 사용할 수 있습니다." 차트는 Kubernetes 리소스를 생성하지만 DNS, TLS, WOPI 호스트 인증, 인그레스 라우팅 및 리소스 크기 조정은 클러스터에 따라 달라집니다. 위의 각 항목을 확인하십시오.
• "인그레스 호스트와 WOPI 호스트 설정이 동일합니다." 하지만 이 둘은 종종 다릅니다. 인그레스 호스트는 Collabora의 공용 IP 주소이고, WOPI 호스트는 스토리지 서버입니다. 각각을 올바른 차트 필드에 입력하세요.
• "복제본 수가 많아질수록 협업이 자동으로 향상됩니다." 상위 차트는 세션 선호도를 문서화하며, 확장이 협업 편집을 방해할 수 있으므로 현재 HPA(고성능 복제)를 비활성화하고 있습니다. 복제본을 하나 또는 의도적으로 고정된 개수로 시작하고 라우팅 선호도를 유지하세요.
• "작은 XML 조각을 사용자 지정 구성으로 제공할 수 있습니다." 차트의 coolwsd_xml_content값은 기본 구성 파일을 대체하며 전체 파일 내용이 필요합니다. 완전하고 버전 호환 가능한 XML 구성 파일이 없는 경우, 별칭 그룹 및 매개변수에 대해서는 차트의 전용 값을 사용하는 것이 좋습니다.

공식 참조

• Collabora Online Helm 차트 배포 README
• 공식 차트 값 및 구성 옵션
• Collabora 차트 패키지 버전
• Kubernetes Ingress 문서