外部GitalyでGitLabチャートを設定する

このドキュメントでは、外部GitalyサービスでこのHelm Chartを設定する方法について説明します。

Gitalyが構成されていない場合は、オンプレミスまたはVMへのデプロイのために、弊社のLinuxパッケージの使用をご検討ください。

外部Gitaly _サービス_は、Gitalyノード、またはPraefectクラスタリングによって提供できます。

チャートを設定する

gitalyチャートと、それが提供するGitalyサービスを無効にし、他のサービスを外部サービスに向けるようにします。

次のプロパティを設定する必要があります:

global.gitaly.enabled: falseに設定して、含まれているGitalyチャートを無効にします。
global.gitaly.external: これは、外部Gitalyサービスの配列です。
global.gitaly.authToken.secret: 認証用のトークンを含むシークレットの名前。
global.gitaly.authToken.key: シークレット内のトークンコンテンツを含むキー。

外部Gitalyサービスは、GitLab Shellの独自のインスタンスを利用します。実装によっては、このチャートのシークレットでそれらを構成するか、このチャートのシークレットを事前定義されたソースのコンテンツで構成することができます。

次のプロパティを設定する必要がある場合があります:

global.shell.authToken.secret: GitLab Shellのシークレットを含むシークレットの名前。
global.shell.authToken.key: シークレット内のシークレットコンテンツを含むキー。

2つの外部Gitalyサービスを含む完全な設定例（external-gitaly.yml）:

global:
  gitaly:
    enabled: false
    external:
      - name: default                   # required, at least one service must be called 'default'.
        hostname: node1.git.example.com # required
        port: 8075                      # optional, default shown
      - name: default2                  # required
        hostname: node2.git.example.com # required
        port: 8075                      # optional, default shown
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled
    authToken:
      secret: external-gitaly-token     # required
      key: token                        # optional, default shown
    tls:
      enabled: false                    # optional, default shown

外部Praefectサービスをセットアップする完全な例。

Praefectサービス名はdefaultである必要があります。

global:
  gitaly:
    enabled: false
    external:
      - name: default                   # required
        hostname: ha.git.example.com    # required
        port: 2305                      # Praefect uses port 2305
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled
    authToken:
      secret: external-gitaly-token     # required
      key: token                        # optional, default shown
    tls:
      enabled: false                    # optional, default shown

上記の設定ファイルを、gitlab.ymlを介した他の設定と組み合わせて使用する場合のインストール例:

helm upgrade --install gitlab gitlab/gitlab  \
  -f gitlab.yml \
  -f external-gitaly.yml

複数の外部Gitaly

実装でこれらのチャートの外部にある複数のGitalyノードを使用している場合は、複数のホストを定義することもできます。必要な複雑さを考慮して、構文がわずかに異なります。

適切な設定セットを示す値ファイルの例が提供されています。この値ファイルの内容は、--set引数を介して正しく解釈されないため、Helmに-f / --valuesフラグを付けて渡す必要があります。

TLS経由で外部Gitalyに接続する

外部GitalyサーバーがTLSポートでリッスンしている場合、GitLabインスタンスにTLS経由で通信させることができます。これを行うには、次の手順を実行する必要があります

Gitalyサーバーの証明書を含むKubernetesシークレットを作成します

kubectl create secret generic gitlab-gitaly-tls-certificate --from-file=gitaly-tls.crt=<path to certificate>

外部Gitalyサーバーの証明書をカスタム認証局のリストに追加します。値ファイルで、以下を指定します
```
global:
  certificates:
    customCAs:
      - secret: gitlab-gitaly-tls-certificate
```
または、helm upgradeコマンドに--setを使用して渡します
```
--set global.certificates.customCAs[0].secret=gitlab-gitaly-tls-certificate
```
すべてのGitalyインスタンスに対してTLSを有効にするには、global.gitaly.tls.enabled: trueを設定します。
```
global:
  gitaly:
    tls:
      enabled: true
```
個々のインスタンスに対して有効にするには、そのエントリにtlsEnabled: trueを設定します。
```
global:
  gitaly:
    external:
      - name: default
        hostname: node1.git.example.com
        tlsEnabled: true
```

これには有効なシークレット名とキーを選択できますが、シークレット内のすべてのキーがマウントされるため、customCAsで指定されたすべてのシークレット間でキーが一意であることを確認してください。これが_クライアント側_であるため、証明書のキーを提供する必要はありません。

GitLabがGitalyに接続できることをテストする

GitLabが外部Gitalyサーバーに接続できることを確認するには:

kubectl exec -it <toolbox-pod> -- gitlab-rake gitlab:gitaly:check

TLSでGitalyを使用している場合は、GitLabチャートがGitaly証明書を信頼しているかどうかを確認することもできます:

kubectl exec -it <toolbox-pod> -- echo | /usr/bin/openssl s_client -connect <gitaly-host>:<gitaly-port>

Gitalyチャートから外部Gitalyに移行する

Gitalyチャートを使用してGitalyサービスを提供していて、すべてのリポジトリを外部Gitalyサービスに移行する必要がある場合は、次のいずれかの方法で実行できます:

リポジトリストレージ移動APIで移行する

この方法:

Gitalyチャートから外部Gitalyサービスにリポジトリを移行するために、リポジトリストレージ移動APIを使用します。
ダウンタイムなしで実行できます。
外部GitalyサービスがGitalyポッドと同じVPC/ゾーン内にある必要があります。
Praefectチャートではテストされておらず、サポートされていません。

ステップ1: 外部GitalyサービスまたはGitaly Cluster (Praefect)をセットアップする

外部Gitalyまたは外部Gitaly Cluster (Praefect)をセットアップします。これらの手順の一部として、チャートインストールからGitalyトークンとGitLab Shellのシークレットを提供する必要があります:

# Get the GitLab Shell secret
kubectl get secret <release>-gitlab-shell-secret -ojsonpath='{.data.secret}' | base64 -d

# Get the Gitaly token
kubectl get secret <release>-gitaly-secret -ojsonpath='{.data.token}' | base64 -d

ここで抽出されたGitalyトークンは、AUTH_TOKENの値に使用する必要があります。
ここで抽出されたGitLab Shellのシークレットは、shellsecretの値に使用する必要があります。

ここで抽出されたGitalyトークンは、PRAEFECT_EXTERNAL_TOKENに使用する必要があります。
ここで抽出されたGitLab Shellのシークレットは、GITLAB_SHELL_SECRET_TOKENに使用する必要があります。

最後に、外部Gitalyサービスのファイアウォールが、KubernetesポッドIP範囲の構成済みGitalyポートでトラフィックを許可していることを確認してください。

ステップ2: 新しいGitalyサービスを使用するようにインスタンスを設定する

外部Gitalyを使用するようにGitLabを構成します。メインのgitlab.yml設定ファイルにGitalyに関する記述がある場合は、それらを削除し、次の内容で新しいmixed-gitaly.ymlファイルを作成します。

以前に追加のGitalyストレージを定義している場合は、新しい設定で同じ名前の対応するGitalyストレージが指定されていることを確認する必要があります。そうでない場合、復元操作は失敗します。

TLSを設定する場合は、TLS経由で外部Gitalyに接続するセクションを参照してください:

global:
  gitaly:
    internal:
      names:
        - default
    external:
      - name: ext-gitaly                # required
        hostname: node1.git.example.com # required
        port: 8075                      # optional, default shown
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled

global:
  gitaly:
    internal:
      names:
        - default
    external:
      - name: ext-gitaly-cluster        # required
        hostname: ha.git.example.com    # required
        port: 2305                      # Praefect uses port 2305
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled

gitlab.ymlファイルとmixed-gitaly.ymlファイルを使用して、新しい設定を適用します:
```
helm upgrade --install gitlab gitlab/gitlab \
  -f gitlab.yml \
  -f mixed-gitaly.yml
```
Toolboxポッドで、GitLabが外部Gitalyに正常に接続できることを確認します:
```
kubectl exec <toolbox pod name> -it -- gitlab-rake gitlab:gitaly:check
```
外部Gitalyがチャートインストールにコールバックできることを確認します:
GitalyサービスがGitLab APIへのコールバックを正常に実行できることを確認します:
sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml
すべてのPraefectノードで、PraefectサービスがGitalyノードに接続できることを確認します:
# Run on Praefect nodes sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes
すべてのGitalyノードで、GitalyサービスがGitLab APIへのコールバックを正常に実行できることを確認します:
# Run on Gitaly nodes sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml

ステップ3: GitalyポッドのIPとホスト名を取得する

リポジトリストレージ移動APIを成功させるには、外部Gitalyサービスがポッドサービスホスト名を使用してGitalyポッドにコールバックできる必要があります。ポッドサービスホスト名を解決できるようにするには、Gitalyプロセスを実行している各外部Gitalyサービスのホストファイルにホスト名を追加する必要があります。

Gitalyポッドとそのそれぞれの内部IPアドレス/ホスト名のリストをフェッチします:

kubectl get pods -l app=gitaly -o jsonpath='{range .items[*]}{.status.podIP}{"\t"}{.spec.hostname}{"."}{.spec.subdomain}{"."}{.metadata.namespace}{".svc\n"}{end}'

Gitalyプロセスを実行している各外部Gitalyサービスの/etc/hostsファイルに、最後のステップからの出力を追加します。
Gitalyプロセスを実行している各外部GitalyサービスからGitalyポッドのホスト名にpingを実行できることを確認します:
```
ping <gitaly pod hostname>
```

接続が確認されたら、リポジトリストレージの移動のスケジュールに進むことができます。

ステップ4: リポジトリストレージの移動をスケジュールする

リポジトリの移動に示されている手順に従って、移動をスケジュールします。

ステップ5: 最終的な設定と検証

複数のGitalyストレージがある場合は、新しいリポジトリの保存場所を設定します。
将来的に、外部Gitaly設定を含む統合されたgitlab.ymlを生成することを検討してください:
```
helm get values <RELEASE_NAME> -o yaml > gitlab.yml
```

gitlab.ymlファイルで内部Gitalyサブチャートを無効にし、新しいdefaultリポジトリストレージを外部Gitalyサービスに向けます。GitLabには、デフォルトのリポジトリストレージが必要です:

global:
  gitaly:
    enabled: false                      # Disable the internal Gitaly subchart
    external:
      - name: ext-gitaly                # required
        hostname: node1.git.example.com # required
        port: 8075                      # optional, default shown
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled
      - name: default                   # Add the default repository storage, use the same settings as ext-gitaly
        hostname: node1.git.example.com
        port: 8075
        tlsEnabled: false

global:
  gitaly:
    enabled: false                      # Disable the internal Gitaly subchart
    external:
      - name: ext-gitaly-cluster        # required
        hostname: ha.git.example.com    # required
        port: 2305                      # Praefect uses port 2305
        tlsEnabled: false               # optional, overrides gitaly.tls.enabled
      - name: default                   # Add the default repository storage, use the same settings as ext-gitaly-cluster
        hostname: ha.git.example.com
        port: 2305
        tlsEnabled: false

新しい設定を適用します:

helm upgrade --install gitlab gitlab/gitlab \
  -f gitlab.yml

オプション。GitalyポッドのIPとホスト名の取得の手順に従って、各外部Gitaly /etc/hostsファイルに加えられた変更を削除します。
すべてが期待どおりに動作していることを確認したら、Gitaly PVCを削除できます:
警告: すべてが期待どおりに動作していることを再確認するまで、Gitaly PVCを削除しないでください。
```
kubectl delete pvc repo-data-<release>-gitaly-0
```

バックアップ/復元メソッドで移行する

この方法:

GitalyチャートPersistentVolumeClaim（PVC）からリポジトリをバックアップし、外部Gitalyサービスに復元します。
すべてのユーザーにダウンタイムが発生します。
Praefectチャートではテストされておらず、サポートされていません。

ステップ1: GitLabチャートの現在のリリースリビジョンを取得する

万が一、移行中に問題が発生した場合、GitLabチャートの現在のリリースリビジョンを取得します。ロールバックを実行する必要がある場合に備えて、出力をコピーして保管しておいてください:

helm history <release> --max=1

ステップ2: 外部GitalyサービスまたはGitaly Cluster (Praefect)を設定する

# Get the GitLab Shell secret
kubectl get secret <release>-gitlab-shell-secret -ojsonpath='{.data.secret}' | base64 -d

# Get the Gitaly token
kubectl get secret <release>-gitaly-secret -ojsonpath='{.data.token}' | base64 -d

ここで抽出されたGitalyトークンは、AUTH_TOKENの値に使用する必要があります。
ここで抽出されたGitLab Shellのシークレットは、shellsecretの値に使用する必要があります。

ここで抽出されたGitalyトークンは、PRAEFECT_EXTERNAL_TOKENに使用する必要があります。
ここで抽出されたGitLab Shellのシークレットは、GITLAB_SHELL_SECRET_TOKENに使用する必要があります。

ステップ3: 移行中にGitの変更が行われないことを確認する

移行のデータの整合性を確保するために、次の手順でGitリポジトリに加えられる変更を防ぎます:

1.メンテナンスモードを有効にする

GitLab Enterprise Editionを使用している場合は、メンテナンスモードをUI、API、またはRailsコンソールから有効にします:

kubectl exec <toolbox pod name> -it -- gitlab-rails runner 'Gitlab::CurrentSettings.update!(maintenance_mode: true)'

2.Runnerポッドをスケールダウンする

GitLab Community Editionを使用している場合は、クラスタリングで実行されているGitLab Runnerポッドをスケールダウンする必要があります。これにより、RunnerがCI/CDジョブを処理するためにGitLabに接続できなくなります。

GitLab Enterprise Editionを使用している場合、この手順はオプションです。メンテナンスモードにより、クラスタリング内のRunnerがGitLabに接続できなくなるためです。

# Make note of the current number of replicas for Runners so we can scale up to this number later
kubectl get deploy -lapp=gitlab-gitlab-runner,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'

# Scale down the Runners pods to zero
kubectl scale deploy -lapp=gitlab-gitlab-runner,release=<release> --replicas=0

3.実行中のCIジョブがないことを確認する

管理者エリアで、CI/CD > ジョブに移動します。このページにはすべてのジョブが表示されますが、実行中ステータスのジョブがないことを確認してください。次の手順に進む前に、ジョブが完了するのを待つ必要があります。

4.Sidekiq cronジョブを無効にする

移行中にSidekiqジョブがスケジュールおよび実行されないようにするには、すべてのSidekiq cronジョブを無効にします:

kubectl exec <toolbox pod name> -it -- gitlab-rails runner 'Sidekiq::Cron::Job.all.map(&:disable!)'

5.実行中のバックグラウンドジョブがないことを確認する

次の手順に進む前に、エンキューされたジョブまたは進行中のジョブが完了するのを待つ必要があります。

管理者エリアで、モニタリングに移動し、バックグラウンドジョブを選択します。
Sidekiqダッシュボードで、Queuesを選択し、次にLive Pollを選択します。
ビジーおよびEnqueuedが0になるまで待ちます。

6.SidekiqとWebサービスのポッドをスケールダウンする

一貫性のあるバックアップが作成されるように、SidekiqとWebサービスのポッドをスケールダウンします。両方のサービスは、後の段階でスケールアップされます:

Sidekiqポッドは、復元ステップ中にスケールバックされます
Webサービスのポッドは、接続をテストするために外部Gitalyサービスに切り替えた後にスケールバックされます

# Make note of the current number of replicas for Sidekiq and Webservice so we can scale up to this number later
kubectl get deploy -lapp=sidekiq,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'
kubectl get deploy -lapp=webservice,release=<release> -o jsonpath='{.items[].spec.replicas}{"\n"}'

# Scale down the Sidekiq and Webservice pods to zero
kubectl scale deploy -lapp=sidekiq,release=<release> --replicas=0
kubectl scale deploy -lapp=webservice,release=<release> --replicas=0

7.クラスタリングへの外部接続を制限する

ユーザーと外部GitLab RunnerがGitLabに変更を加えるのを防ぐために、GitLabへの不要な接続をすべて制限する必要があります。

これらの手順が完了すると、復元が完了するまで、GitLabはブラウザで完全に利用できなくなります。

移行中に新しい外部Gitalyサービスがクラスタリングにアクセスできるようにするために、外部GitalyサービスのIPアドレスを唯一の外部例外としてnginx-ingress設定に追加する必要があります。

次の内容のingress-only-allow-ext-gitaly.ymlファイルを作成します:
```
nginx-ingress:
  controller:
    service:
      loadBalancerSourceRanges:
       - "x.x.x.x/32"
```
x.x.x.xは、外部GitalyサービスのIPアドレスである必要があります。
gitlab.ymlファイルとingress-only-allow-ext-gitaly.ymlファイルの両方を使用して、新しい設定を適用します:
```
helm upgrade <release> gitlab/gitlab \
  -f gitlab.yml \
  -f ingress-only-allow-ext-gitaly.yml
```

8.リポジトリのチェックサムのリストを作成します

バックアップを実行する前に、すべてのGitLabリポジトリをチェックして、リポジトリのチェックサムのリストを作成します。移行後にチェックサムをdiffできるように、出力をファイルにパイプします:

kubectl exec <toolbox pod name> -it -- gitlab-rake gitlab:git:checksum_projects > ~/checksums-before.txt

ステップ4: すべてのリポジトリをバックアップします

リポジトリのみのバックアップを作成します:

kubectl exec <toolbox pod name> -it -- backup-utility --skip artifacts,ci_secure_files,db,external_diffs,lfs,packages,pages,registry,terraform_state,uploads

ステップ5: 新しいGitalyサービスを使用するようにインスタンスを設定する

Gitalyサブチャートを無効にし、外部Gitalyを使用するようにGitLabを設定します。メインのgitlab.yml設定ファイルにGitalyに関する記述がある場合は、それらを削除し、次の内容で新しいexternal-gitaly.ymlファイルを作成します。