Helmを使用してKubernetes上にCollabora CODEをセットアップする方法

Collabora Online のページは、CODE ポッドが実行された後でも空白のままだったり、オフィス サーバーが利用できないと表示されたりすることがあります。正常なポッドはセットアップの一部にすぎません。ブラウザと WOPI アプリケーションがパブリック ホスト名経由で Collabora にアクセスできる必要があり、TLS とプロキシの設定が一致している必要があり、Collabora が WOPI ホストを信頼している必要があります。公式の Collabora Helm チャートはサーバーを Kubernetes にデプロイしますが、Nextcloud、ownCloud、またはその他の WOPI ホストをインストールまたは構成するわけではありません。

このガイドでは、Collaboraが管理するNGINX Ingressの例を含むHelmチャートを使用します。サンプルドメインはご自身のドメインに置き換えてください。CODEはCollabora Online Development Editionの略で、評価、家庭での使用、小規模チーム向けに設計されています。Collaboraは、安定したサポート付きリリースが必要な本番環境での使用は推奨していません。本番ワークロードについては、サポートされているCollabora Online製品とそのライセンスおよびサポート条件を検討してください。

インストール前に必要なもの

• 動作するKubernetesクラスター、kubectlおよびクラスターにアクセスできるHelm 3。
• クラスターにインストールされたIngressコントローラー。以下の例ではingress-nginxを使用していますが、CollaboraチャートにはHAProxyに関する説明もあり、他のルーティング構成もサポートしています。
• office.example.comパブリックイングレスアドレスを指すDNS名、およびCollaboraネームスペースにKubernetes Secretとして保存されたTLS証明書。
• 例えば、URLが のような Nextcloud などの WOPI アプリケーションcloud.example.com。Collabora は WOPI アプリケーションにアクセスできる必要があり、アプリケーションとユーザーのブラウザは Collabora にアクセスできる必要があります。
• 明確なTLSプラン。この例では、HTTPSをイングレスで終端し、クラスタ内のCollaboraサービスにHTTPを送信します。

自宅やテスト環境での迅速なデプロイには、単一のCODEポッドを使用することでルーティングを簡素化できます。レプリカを複数作成することで容量を向上させることができますが、CollaboraのKubernetesガイドでは、同じドキュメントの編集セッションが同じポッドに到達するように、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 を作成します。プレースホルダーのパスワードを強力なシークレットに置き換えるか、組織のシークレット マネージャーまたは GitOps シークレット ワークフローを使用して 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'

このチャートは、既存のシークレットを参照することをサポートしています。これを有効にすることで、管理者パスワードをHelmの値ファイルに直接記述する必要がなくなります。シークレットは、このデプロイメントを管理する名前空間とユーザーまたはサービスアカウントに限定してください。

ステップ3：ホスト名、WOPIホスト、およびイングレスを設定する

という名前のファイルを作成しますcollabora-values.yaml。この例では、ingress-nginx、という名前のTLSシークレット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.comはHTTPSを使用し、イングレスはクラスタ内部でHTTP経由でCollaboraにトラフィックを転送します。イングレスがTLSパススルーまたは別の内部プロトコルを使用している場合は、これらのSSLフラグをそのままコピーせず、実際のTLSパスとチャートの現在の値に合わせて調整してください。

TLS シークレットがcollabora名前空間に存在することを確認してください。別のイングレス コントローラーを使用する場合は、クラスとアノテーションをそのコントローラーのドキュメントに記載されている同等のものに置き換えてください。WebSocket トラフィックを有効にし、長時間接続を許可してください。コントローラーのデフォルト設定はコントローラーによって異なります。

ステップ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アプリケーションを接続する前に、ポッドがReady状態になるまでお待ちください。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 を と比較してくださいcollabora.aliasgroups。スキーム、ホスト名、ポートを確認し、正当な代替ホスト名を意図的に追加してください。影響を理解していない限り、広範なホストパターンは避けてください。複数の WOPI アプリケーションを使用する場合は、すべてのドメインを許可するのではなく、チャートに記載されているエイリアス グループ構造に従って、各ホストを許可してください。

1つのポッドを超えて規模を拡大すべきタイミングはいつですか？

小規模なテストでは、オートスケーリングを無効にしたレプリカを1つ使用することで、ルーティングの複雑さを回避できます。複数のレプリカを使用する場合は、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がPodをReadyと報告し、ServiceとIngressが存在することを確認しますkubectl get pods,svc,ingress -n collabora。
2. 公開されている検出エンドポイントを確認してください。ブラウザやプロキシのエラーではなく、XMLが返されるはずです。

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

3. WOPIアプリケーションを開き、テスト文書を編集します。エディタが読み込まれ、変更が保存され、文書を再度開くと保存された内容が表示されることを確認してください。
4. 複数のレプリカを使用する場合は、同じドキュメントを2つのセッションで開き、両方のセッションで再接続を繰り返すことなく共同作業ができることを確認してください。これにより、セッションアフィニティの欠落を特定するのに役立ちます。
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シークレット、およびサービスエンドポイントを確認してください。IngressがチャートのサービスポートでCollaboraサービスに到達できることを確認してください。
• 検出機能は動作するものの、エディタが空白のままの場合：ブラウザのコンソールエラーとプロキシログを確認してください。HTTPS終端設定、WebSocket処理、および長時間のリクエストタイムアウトを確認してください。
• 認証されていない WOPI ホスト: WOPI アプリケーションの発信元を許可しますaliasgroups。オフィス サーバーのホスト名を置き換えないでください。
• Podが再起動または強制終了された場合：コンテナログを検査しkubectl describe pod、利用可能なクラスタに対して現実的なリソース要求と制限を設定します。
• レプリカを追加すると編集が不安定になる場合があります。WOPISrcベースのアフィニティを確認し、リクエストをルーティングする際にコントローラがクエリ引数を保持していることを確認してください。

チャートがインストールされ、検出エンドポイントにアクセス可能で、WOPIアプリケーションを通じて実際のドキュメントが正常に開かれて保存された場合、コアCODEデプロイメントは正常に動作しています。チャートのバージョンを固定し、チャートのアップグレード、イングレスの変更、またはスケーリングの変更後にこれらのチェックを繰り返してください。

公式資料

• Collaboraが管理するKubernetes Helmチャートとデプロイメントガイド
• Collabora Helmチャートの値
• Collaboraのチャートリリース
• Collabora Online Development Edition (CODE) のガイダンス
• Nextcloud Office 設定マニュアル
• ingress-nginx アノテーションのドキュメント
• Helmインストールコマンドリファレンス