Kubernetes向けONLYOFFICE Docs

1. ONLYOFFICE Docsライセンスをデプロイする

1. シークレットを作成する

   有効なONLYOFFICE Docsライセンスをお持ちの場合、ファイルからlicenseというシークレットを作成します：

   $ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic

   ここで、SECRET_LICENSE_NAMEはライセンスを持つ将来のシークレットの名前です。

   ソースライセンスファイル名は「license.lic」である必要があります。この名前は作成されたシークレットのフィールドとして使用されます。
   既存のライセンスファイルを持つシークレットを作成せずにインストールを行う場合、空のシークレットlicense 自動的に作成されます。ライセンスを使用して既存のシークレットを更新する方法については、こちらをご覧ください。
2. ONLYOFFICE Docsをインストールする際のパラメータ指定

   ONLYOFFICE Docsをインストールする際には、license.existingSecret=[SECRET_LICENSE_NAME]パラメータを指定してください。

   $ helm install documentserver onlyoffice/docs --set license.existingSecret=[SECRET_LICENSE_NAME]

   ONLYOFFICE Docsを既にインストールした後でライセンスを追加する必要がある場合は、ステップ1.1を実行し、その後helm upgrade documentserver onlyoffice/docs --set license.existingSecret=[SECRET_LICENSE_NAME] --no-hooksコマンドまたはhelm upgrade documentserver -f ./values.yaml onlyoffice/docs --no-hooksを実行してください。パラメータがvalues.yamlファイルに指定されている場合。

2. ONLYOFFICE Docsのデプロイ

リリース名documentserverでONLYOFFICE Docsをデプロイするには：

$ helm install documentserver onlyoffice/docs

このコマンドは、デフォルトの設定でKubernetesクラスターにONLYOFFICE Docsをデプロイします。インストール中に設定できるパラメータはパラメータセクションにリストされています。

3. ONLYOFFICE Docsのアンインストール

documentserverデプロイメントをアンインストール/削除するには：

$ helm delete documentserver

helm deleteコマンドを実行すると、ONLYOFFICE Docsを完全に削除する前にいくつかの準備作業を行うフックが起動します。これにはサーバーの停止、使用されたPVCとデータベーステーブルのクリーンアップが含まれます。デフォルトのフック実行時間は300秒です。実行時間は--timeout [time]を使用して変更できます。例えば：

$ helm delete documentserver --timeout 25m

準備作業なしでONLYOFFICE Docsを削除したい場合は、次のコマンドを実行してください：

$ helm delete documentserver --no-hooks

helm deleteコマンドは、チャートに関連付けられたすべてのKubernetesコンポーネントを削除し、リリースを削除します。

4. パラメータ

• *注: イメージリポジトリの値にはプレフィックス -de が指定されており、これはソリューションタイプを意味します。可能なオプション：
  • -de. 商用デベロッパー版
  • -ee. 商用エンタープライズ版

  このパラメーターのデフォルト値は、ONLYOFFICE Document Server デベロッパー版を指します。このエディションについて詳しく知り、他のエディションと比較するには、このページの比較表をご覧ください。

各パラメーターを指定するには、--set key=value[,key=value] 引数を helm install に使用します。例えば、

$ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

このコマンドは、ONLYOFFICE Docs を HTTPS 経由で公開します。

または、チャートをインストールする際にパラメーターの値を指定する YAML ファイルを提供することもできます。例えば、

$ helm install documentserver -f values.yaml onlyoffice/docs

5. 設定とインストールの詳細

1. 例のデプロイメント（オプション）

   例をデプロイするには、example.enabled パラメーターを true に設定します：

   $ helm install documentserver onlyoffice/docs --set example.enabled=true

2. メトリクスのデプロイメント（オプション）

   メトリクスをデプロイするには、metrics.enabled を true に設定します：

   $ helm install documentserver onlyoffice/docs --set metrics.enabled=true

   Grafana を使用してメトリクスを視覚化したい場合は、grafana.enabled を true に設定します。Grafana にアクセスするために Nginx Ingress を使用したい場合は、grafana.ingress.enabled を true に設定します：

   $ helm install documentserver onlyoffice/docs --set grafana.enabled=true --set grafana.ingress.enabled=true

3. ONLYOFFICE Docs の公開
   1. ONLYOFFICE Docs をサービス経由で公開（HTTP のみ）
      ONLYOFFICE Docs を HTTPS 経由で公開する場合は、このステップをスキップしてください。

      この公開タイプは、パフォーマンスのオーバーヘッドが最も少なく、ONLYOFFICE Docs にアクセスするためのロードバランサーを作成します。外部 TLS 終端を使用し、k8s クラスター内に他の WEB アプリケーションがない場合にこの公開タイプを使用してください。

      ONLYOFFICE Docs をサービス経由で公開するには、service.type パラメーターを LoadBalancer に設定します：

      $ helm install documentserver onlyoffice/docs --set service.type=LoadBalancer,service.port=80

      documentserver サービスの IP を取得するには、次のコマンドを実行します：

      $ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

      その後、ONLYOFFICE Docs は http://DOCUMENTSERVER-SERVICE-IP/ で利用可能になります。

      サービス IP が空の場合は、documentserver サービスのホスト名を取得してみてください：

      $ kubectl get service documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

      この場合、ONLYOFFICE Docs は http://DOCUMENTSERVER-SERVICE-HOSTNAME/ で利用可能になります。

   2. ONLYOFFICE Docs を Ingress 経由で公開
      1. Kubernetes Nginx Ingress コントローラーのインストール

         クラスターに Nginx Ingress コントローラーをインストールするには、次のコマンドを実行します：

         $ helm install nginx-ingress ingress-nginx/ingress-nginx --set controller.publishService.enabled=true,controller.replicaCount=2

         同じパラメーターで Nginx Ingress をインストールし、Prometheus によって収集される ingress-nginx メトリクスの公開を有効にするには、次のコマンドを実行します：

         $ helm install nginx-ingress -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/ingress_values.yaml ingress-nginx/ingress-nginx

         Helm を使用して Nginx Ingress をインストールする詳細については、こちらをご覧ください。

      2. ONLYOFFICE Docs を HTTP 経由で公開
         ONLYOFFICE Docs を HTTPS 経由で公開する場合は、このステップをスキップしてください。

         この公開タイプは、サービス経由の公開と比較してパフォーマンスのオーバーヘッドが多く、ONLYOFFICE Docs にアクセスするためのロードバランサーも作成します。外部 TLS 終端を使用し、k8s クラスター内に複数の WEB アプリケーションがある場合にこのタイプを使用します。これにより、エントリーポイントのパフォーマンスを最適化し、クラスターの支払いを削減できます。プロバイダーは各ロードバランサーに対して料金を請求することがあります。

         Ingress HTTP 経由で ONLYOFFICE Docs を公開するには、ingress.enabled パラメーターを true に設定します：

         $ helm install documentserver onlyoffice/docs --set ingress.enabled=true

         documentserver ingress IP を取得するには、次のコマンドを実行します：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

         その後、ONLYOFFICE Docs は http://DOCUMENTSERVER-INGRESS-IP/ で利用可能になります。

         ingress IP が空の場合は、documentserver ingress のホスト名を取得してみてください：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

         この場合、ONLYOFFICE Docs は http://DOCUMENTSERVER-INGRESS-HOSTNAME/ で利用可能になります。

      3. ONLYOFFICE Docs を HTTPS 経由で公開

         この公開タイプは、ONLYOFFICE Docs の内部 TLS 終端を有効にすることができます。

         SSL 証明書を含む tls シークレットを作成します。

         SSL 証明書と秘密鍵を tls.crt および tls.key ファイルに入れ、次を実行します：

         $ kubectl create secret generic tls \
           --from-file=./tls.crt \
           --from-file=./tls.key

         $ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.ssl.enabled=true,ingress.host=example.com

         documentserver ingress IP を取得するには、次のコマンドを実行します：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].ip}"

         ingress IP が空の場合は、documentserver ingress のホスト名を取得してみてください：

         $ kubectl get ingress documentserver -o jsonpath="{.status.loadBalancer.ingress[*].hostname}"

         DNS プロバイダーを通じて、documentserver ingress IP またはホスト名をドメイン名に関連付けます。

         その後、ONLYOFFICE Docs は https://your-domain-name/ で利用可能になります。

      4. Let's Encrypt 証明書を使用して HTTPS 経由で ONLYOFFICE Docs を公開
         • Helm リポジトリを追加します：

           $ helm repo add jetstack https://charts.jetstack.io
           $ helm repo update

         • cert-manager のインストール

           $ helm install cert-manager --version v1.17.4 jetstack/cert-manager \
             --namespace cert-manager \
             --create-namespace \
             --set crds.enabled=true \
             --set crds.keep=false

           次に、ingress.enabled、ingress.ssl.enabled、ingress.letsencrypt.enabled パラメーターを true に設定してインストールまたはアップグレードを実行します。また、複数のドメイン名を使用する場合は、ingress.letsencrypt.email、ingress.host、または ingress.tenants パラメーターに独自の値を設定します（例：--set "ingress.tenants={tenant1.example.com,tenant2.example.com}"）。

   3. 仮想パスで ONLYOFFICE Docs を公開

      この公開タイプでは、ONLYOFFICE Docs を仮想パスで公開できます。例えば、http://your-domain-name/docs。Ingress 経由で仮想パスで ONLYOFFICE Docs を公開するには、ingress.enabled、ingress.host、および ingress.path パラメーターを設定します。

      $ helm install documentserver onlyoffice/docs --set ingress.enabled=true,ingress.host=your-domain-name,ingress.path=/docs

      仮想パス設定に対応したイングレスコントローラーの一覧：

      • KubernetesによるIngress NGINX
      • NGINXによるNGINX Ingress
      • HAProxyによるHAProxy Ingress

      KubernetesによるIngress NGINXを使用して仮想パス設定を行う場合、ingress.pathにパターン(/|$)(.*)を追加します。例えば、/docsは/docs(/|$)(.*)となります。

4. OpenShiftでルートを介してONLYOFFICE Docsを公開する

   この公開方法を使用すると、OpenShiftでルートを介してONLYOFFICE Docsを公開できます。ルートを介してONLYOFFICE Docsを公開するには、次のパラメーターを使用します：openshift.route.enabled、openshift.route.host、openshift.route.path。

   $ helm install documentserver onlyoffice/docs --set openshift.route.enabled=true,openshift.route.host=your-domain-name,openshift.route.path=/docs

   tls終端のためには、OpenShiftのウェブコンソールを介して手動で証明書をルートに追加します。

6. ONLYOFFICE Docsのスケーリング（オプション）

1. 水平Podオートスケーリング

   オートスケーリングを有効にすると、docserviceおよびconverterデプロイメントのレプリカ数が、値とメトリックの種類に基づいて自動的に計算されます。

   リソースメトリックの場合、API metrics.k8s.ioが登録されている必要があります。これは通常、metrics-serverによって提供され、クラスタアドオンとして起動できます。

   ターゲット利用率値（target.type==Utilization）を使用するには、デプロイメントでresources.requestsの値が指定されている必要があります。

   水平Podオートスケーリングの詳細については、こちらをご覧ください。

   docserviceデプロイメントのHPAを有効にするには、docservice.autoscaling.enabled=trueパラメーターを指定します。この場合、docservice.replicasパラメーターは無視され、レプリカ数はHPAによって制御されます。

   同様に、converterデプロイメントのHPAを有効にするには、converter.autoscaling.enabled=trueパラメーターを指定します。この場合、converter.replicasパラメーターは無視され、レプリカ数はHPAによって制御されます。

   autoscaling.enabledパラメーターが有効になっている場合、デフォルトでオートスケーリングはCPU利用率の平均パーセンテージに基づいてレプリカ数を調整します。他の設定可能なオートスケーリングパラメーターについては、パラメーター表をご覧ください。

2. 手動スケーリング

   docserviceおよびconverterデプロイメントは、デフォルトでそれぞれ2つのPodで構成されています。

   docserviceデプロイメントをスケールするには、次のコマンドを使用します：

   $ kubectl scale -n default deployment docservice --replicas=POD_COUNT

   ここで、POD_COUNTはdocserviceのPodの数です。

   converterデプロイメントをスケールする場合も同様です：

   $ kubectl scale -n default deployment converter --replicas=POD_COUNT

7. ONLYOFFICE Docsの更新

更新のためのパラメーターを設定する必要があります。例えば、

$ helm upgrade documentserver onlyoffice/docs \
  --set docservice.image.tag=[version]

または、values.yamlファイルを修正して次のコマンドを実行します：

$ helm upgrade documentserver -f values.yaml onlyoffice/docs

helm upgradeコマンドを実行すると、ONLYOFFICE Docsをシャットダウンし、データベースをクリーンアップするフックが実行されます。これは、ONLYOFFICE Docsのバージョンを更新する際に必要です。デフォルトのフック実行時間は300秒です。実行時間は--timeout [time]を使用して変更できます。例えば：

$ helm upgrade documentserver -f values.yaml onlyoffice/docs --timeout 15m

ONLYOFFICE Docsのバージョン以外のパラメーターを更新したい場合は、hooksなしでhelm upgradeコマンドを実行します。例えば：

$ helm upgrade documentserver onlyoffice/docs --set jwt.enabled=false --no-hooks

更新をロールバックするには、次のコマンドを実行します：

$ helm rollback documentserver

8. ONLYOFFICE Docsのシャットダウン（オプション）

シャットダウンを実行するには、次のコマンドを実行します：

$ kubectl apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n <NAMESPACE>

ここで、<NAMESPACE>はONLYOFFICE Docsがインストールされている名前空間です。指定されていない場合、デフォルト値はdefaultです。

例：

$ kubectl apply -f https://raw.githubusercontent.com/ONLYOFFICE/Kubernetes-Docs/master/sources/shutdown-ds.yaml -n onlyoffice

ジョブを作成したPod shutdown-dsが正常に実行された後、このジョブを次のコマンドで削除します：

$ kubectl delete job shutdown-ds -n <NAMESPACE>

ONLYOFFICE Docsを停止した後に再起動する必要がある場合は、docserviceおよびconverterのPodを再起動します。例えば、次のコマンドを使用します：

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

9. ONLYOFFICE Docsライセンスの更新（オプション）

バージョンv5.1.1以降では、新しいライセンスでシークレットを再作成するだけで、ポッドを削除したり再起動したりせずにライセンスを更新できます。documentserverは、ライセンスファイルを置き換えた後に動的に読み込み直すことができます。例えば：

ライセンスを更新するには、次の手順を実行する必要があります：

• 新しいキーを含むlicense.licファイルをディレクトリに配置します
• 次のコマンドを実行します：

  $ kubectl delete secret [SECRET_LICENSE_NAME] -n <NAMESPACE>
  $ kubectl create secret generic [SECRET_LICENSE_NAME] --from-file=path/to/license.lic -n <NAMESPACE>

  ここで、SECRET_LICENSE_NAMEはライセンスを持つ既存のシークレットの名前です

これで完了です。documentserverは新しいライセンスを自動的に読み込みます。

$ kubectl delete pod converter-*** docservice-*** -n <NAMESPACE>

10. ONLYOFFICE Docsインストールテスト（オプション）

次のコマンドを実行することで、ONLYOFFICE Docsの可用性と接続された依存関係へのアクセスをテストできます：

$ helm test documentserver -n <NAMESPACE>

出力には次の行が含まれているはずです：

Phase: Succeeded

helm testコマンドの結果として実行されるPodのログを表示するには、次のコマンドを実行します：

$ kubectl logs -f test-ds -n <NAMESPACE>

ONLYOFFICE Docsの可用性チェックは優先事項と見なされるため、エラーで失敗した場合、テストは失敗と見なされます。

その後、次のコマンドを実行してtest-ds Podを削除できます：

$ kubectl delete pod test-ds -n <NAMESPACE>

11. プライベートk8sクラスタでのジョブ実行（オプション）

インストール、更新、ロールバック、および削除のためのJobを実行する際、起動されるコンテナは最新のSQLスクリプトをダウンロードするためにインターネットアクセスが必要です。k8sクラスタ内でコンテナの外部ネットワークへのアクセスが禁止されている場合、privateCluster=trueパラメーターを設定し、必要なSQLスクリプトを含むConfigMapを手動で作成することでこれらのジョブを実行できます。

これを行うには、次のコマンドを実行します：

クラスタにremove-db-scriptsおよびinit-db-scriptsのconfigmapsが既にある場合、それらを削除します：

$ kubectl delete cm remove-db-scripts init-db-scripts

データベースのクリーンアップとデータベーステーブルの作成のために、ONLYOFFICE Docsのデータベーススクリプトをダウンロードします：

データベースサーバーとしてPostgreSQLを選択した場合：

$ wget -O removetbl.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/postgresql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/postgresql/createdb.sql

データベースサーバーとしてMySQLを選択した場合：

$ wget -O removetbl.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/mysql/removetbl.sql
$ wget -O createdb.sql https://raw.githubusercontent.com/ONLYOFFICE/server/master/schema/mysql/createdb.sql

これらからConfigMapを作成します：

$ kubectl create configmap remove-db-scripts --from-file=./removetbl.sql
$ kubectl create configmap init-db-scripts --from-file=./createdb.sql

ConfigMapおよびそれが作成されるファイルに異なる名前を指定した場合、対応するジョブの適切なパラメータを設定します：

• データベースクリーンアップ用スクリプトにはexistingConfigmap.tblRemove.nameとexistingConfigmap.tblRemove.keyName
• データベーステーブル作成用スクリプトにはexistingConfigmap.tblCreate.nameとexistingConfigmap.tblCreate.keyName

次に、helm install|upgrade|rollback|deleteコマンドを実行する際に、パラメータprivateCluster=trueを設定します

12. 情報ページへのアクセス（オプション）

/infoページへのアクセスはデフォルトで制限されています。アクセスを許可するためには、proxy.infoAllowedIPパラメータを使用してIPアドレスまたはサブネット（この場合はプロキシコンテナクライアントになります）を指定する必要があります。Kubernetesネットワークの相互作用の特性を考慮すると、標準的なシナリオではありませんが、ユーザーの元のIP（プロキシクライアント）を取得することが可能です。一般的には、Pod / ノード / ロードバランサーのアドレスが実際のクライアントとなるため、これらのアドレスを使用します。この場合、情報ページへのアクセスは誰でも可能になります。Nginxの基本認証を使用してinfoページへのアクセスをさらに制限することができ、proxy.infoAllowedUserパラメータ値を設定し、proxy.infoAllowedPasswordパラメータを使用してパスワードを設定することで有効にすることができます。または、proxy.infoAllowedExistingSecretパラメータを設定して既存のパスワードを持つシークレットを使用することもできます。