アップグレードガイド

GitLab インストールをアップグレードする前に、アップグレードしたい特定のリリースに対応する変更履歴をチェックし、新しい GitLab チャートのバージョンに関連するリリースノートを探す必要があります。

注意:3.x バージョンの Chart から4.0 の最新リリースにアップグレードする場合、アップグレードを動作させるために、まず3.3.x の最新パッチリリースにアップデートする必要があります。4.0 のリリースノートには、サポートされているアップグレードパスが記載されています。
注意:2.x バージョンの Chart から最新の 3.0 リリースにアップグレードする場合、アップグレードを動作させるために、まず2.6.x パッチの最新リリースにアップデートする必要があります。3.0 リリースノートには、サポートされているアップグレードパスが記載されています。

また、現在の値の一部が非推奨になる可能性があるため、--reuse-values を使用する代わりに、helm upgrade --set key=value 構文または-f values.yml を使用してすべての値を提供する必要があることに注意してください。

**helm upgrade gitlab gitlab/gitlab -f gitlab.yaml注：**helm get values <release name>を使えば、以前の--set 引数をクリーンに取り出すことができます。 この引数をファイル（helm get values <release name> > gitlab.yaml）に渡すと、このファイルを-fを使って安全に渡すことができます。--reuse-values

ChartのバージョニングとGitLabのバージョニングのマッピングはこちらにあります。

ステップ

注:4.0 バージョンの Chart にアップグレードする場合は、4.0 の手動アップグレード手順に従ってください。
注:3.0 バージョンの Chart にアップグレードする場合は、3.0 の手動アップグレード手順に従ってください。

以下はGitLabを新しいバージョンにアップグレードする手順です：

  1. アップグレードしたいバージョンの変更履歴を確認してください。
  2. デプロイのドキュメントを順を追って読んでください。

  3. で以前の--set 引数を抽出します。 

    helm get values gitlab > gitlab.yaml
  4. 設定するすべての値を決定します。
  5. GitLab Operatorを使用したい場合は、Operatorのインストールで説明されている手順に従ってください。

  6. ステップ 4 で抽出したすべての--set 引数を使用して、アップグレードを実行します。 

    helm upgrade gitlab gitlab/gitlab \
  --version <new version> \
  -f gitlab.yaml \
  --set gitlab.migrations.enabled=true \
  --set ...
注意:データベースのメジャーアップグレードの際には、gitlab.migrations.enabled をfalseに設定するようお願いしています。今後のアップデートの際には、明示的にtrue に戻すようにしてください。

バンドルされているPostgreSQLチャートのアップグレード

このチャートの4.0.0 リリースの一環として、バンドルされているPostgreSQL チャートを 7.7.0 から8.9.4にアップグレードしました。 これは、ドロップインで置き換えられるものではありません。 データベースをアップグレードするには、手動で手順を実行する必要があります。 手順は、4.0 アップグレード手順に記載されています。

このChartの3.0.0 リリースの一環として、バンドルされているPostgreSQLのChartを0.11.0から7.7.0にアップグレードしました。 これはドロップインで置き換えられるものではありません。 データベースをアップグレードするには、手動で手順を実行する必要があります。 手順は3.0のアップグレード手順で文書化されています。

4.0リリースのアップグレード手順

4.0.0 リリースでは、アップグレードを実行するために手動による手順が必要です。

注意：アップグレードを行う前にバックアップを取ることを忘れないでください。

バンドルされているPostgreSQLを使用している場合、このアップグレードを実行する最善の方法は、古いデータベースをバックアップし、新しいデータベースインスタンスにリストアすることです。

注意:ドキュメントに記載されているとおりにこれらの手順を実行しないと、データベースを失う可能性があります。 別のバックアップがあることを確認してください。

既存データベースの準備

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合は、この手順を実行する必要はありません。
注意:同じネームスペースに複数のChartがインストールされている場合、データベースアップグレードスクリプトにHelmのリリース名を渡す必要がある場合があります。 後述のコマンド例では、bash -s STAGE をbash -s -- -r RELEASE STAGE に置き換えてください。
注意:kubectl コンテキストのデフォルト以外のネームスペースにChartをインストールした場合は、 そのネームスペースをdatabase-upgradeスクリプトに渡す必要があります。 後述のコマンド例では、bash -s STAGE をbash -s -- -n NAMESPACE STAGE に置き換えてください。 このオプションは、-r RELEASEとともに使用できます。kubectl config set-context --current --namespace=NAMESPACEを実行するか、kubectxからkubens を使用して、 コンテキストのデフォルトのネームスペースを設定できます。

pre ステージでは、task-runner ポッド内の backup-utility スクリプトを使用してデータベースのバックアップが作成され、設定された s3 バケット (デフォルトでは MinIO) に保存されます： 

# GITLAB_RELEASE should be the version of the chart you are installing, starting with 'v': v4.0.0
curl -s https://gitlab.com/gitlab-org/charts/gitlab/raw/${GITLAB_RELEASE}/scripts/database-upgrade | bash -s pre

既存のPostgreSQLデータの削除

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合は、この手順を実行する必要はありません。
注意：前のステップでデータベースのバックアップを作成したことを確認してください。 バックアップがないと、GitLabのデータは失われます。

この4.0 リリースでは、デフォルトでバンドルされているPostgreSQLのバージョンが10.9.0から11.7.0に更新されます。 データ形式が変更されたため、アップグレードする前に既存のPostgreSQL StatefulSetを削除する必要が 4.0あります。 StatefulSetは次の手順で再作成されます。 

kubectl delete statefulset RELEASE-NAME-postgresql
kubectl delete pvc data-RELEASE_NAME-postgresql-0

GitLabのアップグレード

GitLabのアップグレードは、標準的な手順に従い、以下を追加してください：

バンドルされているPostgreSQLを使用している場合は、アップグレードコマンドで以下のフラグを使用して移行を無効にしてください：

  1. --set gitlab.migrations.enabled=false

バンドルされているPostgreSQLについては、後のステップでデータベースの移行を実行します。

データベースの復元

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合は、この手順を実行する必要はありません。
注意：このスクリプトを正常に実行するには、Bash 4.0以上を使用している必要があります。Bashの連想配列を使用する必要があるからです。

  1. タスクランナーポッドのアップグレードが完了するまで待ちます。 RELEASE_NAME には、以下の GitLab リリースの名前を指定します。helm list 

    kubectl rollout status -w deployment/RELEASE_NAME-task-runner

  2. task-runner ポッドが正常にデプロイされたら、post の手順を実行します：

    このステップでは以下のことを行います：

    1. webservice、sidekiq、gitlab-exporter のデプロイに対してレプリカを 0 に設定します。これにより、バックアップのリストア中に他のアプリケーションがデータベースを変更することを防ぎます。
    2. 前ステージで作成したバックアップからデータベースをリストアします。
    3. 新しいバージョンのデータベース移行を実行します。
    4. 最初のステップからデプロイの一時停止を解除します。 
    # GITLAB_RELEASE should be the version of the chart you are installing, starting with 'v': v4.0.0
curl -s https://gitlab.com/gitlab-org/charts/gitlab/raw/${GITLAB_RELEASE}/scripts/database-upgrade | bash -s post

4.0リリースアップグレードプロセスのトラブルシューティング

  • アップグレード中に何らかの障害が発生した場合は、gitlab-upgrade-check ポッドの説明で詳細を確認するとよいでしょう： 

     kubectl get pods -lrelease=RELEASE,app=gitlab
 kubectl describe pod <gitlab-upgrade-check-pod-full-name>

3.0リリースのアップグレード手順

3.0.0 リリースでは、アップグレードを実行するために手動による手順が必要です。

注意：アップグレードを行う前にバックアップを取ることを忘れないでください。

バンドルされている PostgreSQL を使用している場合、このアップグレードを実行する最良の方法は、古いデータベースをバックアップし、新しいデータベースインスタンスにリストアすることです。 手順の一部を自動化しましたが、別の方法として、手動で手順を実行することもできます。

注意:ドキュメントに記載されているとおりにこれらの手順を実行しないと、データベースが失われる可能性があります。 別のバックアップがあることを確認してください。

既存データベースの準備

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合は、この手順を実行する必要はありません。
注意:同じネームスペースに複数のChartがインストールされている場合、データベースアップグレードスクリプトにHelmのリリース名を渡す必要がある場合があります。 後述のコマンド例では、bash -s STAGE をbash -s -- -r RELEASE STAGE に置き換えてください。
注意:kubectl コンテキストのデフォルト以外のネームスペースにChartをインストールした場合は、 そのネームスペースをdatabase-upgradeスクリプトに渡す必要があります。 後述のコマンド例では、bash -s STAGE をbash -s -- -n NAMESPACE STAGE に置き換えてください。 このオプションは、-r RELEASEとともに使用できます。kubectl config set-context --current --namespace=NAMESPACEを実行するか、kubectxからkubens を使用して、 コンテキストのデフォルトのネームスペースを設定できます。

pre ステージでは、task-runner ポッド内の backup-utility スクリプトを使用してデータベースのバックアップが作成され、設定された s3 バケット (デフォルトでは MinIO) に保存されます： 

# GITLAB_RELEASE should be the version of the chart you are installing, starting with 'v': v3.0.0
curl -s https://gitlab.com/gitlab-org/charts/gitlab/-/raw/${GITLAB_RELEASE}/scripts/database-upgrade  | bash -s pre

クラスター・データベースの秘密の準備

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合：

  • global.psql.password.keyを提供している場合は、この手順を実行する必要はありません。
  • global.psql.password.secretを指定した場合は、global.psql.password.key に既存のキーの名前を設定して、この手順を回避します。

アプリケーション データベース キーの秘密鍵がpostgres-passwordからpostgresql-passwordに変更されています。 以下に説明する 2 つの手順のいずれかを使用して、データベース パスワードの秘密鍵を更新します：

  1. 自動生成された PostgreSQL パスワードを使いたい場合は、既存の secret を削除してアップグレードが新しいパスワードを生成するようにしてください。 RELEASE-NAME には、helm listからの GitLab リリースの名前を指定します： 

    # Create a local copy of the old secret in case we need to restore the old database
kubectl get secret RELEASE-NAME-postgresql-password -o yaml > postgresql-password.backup.yaml
# Delete the secret so a new one can be created
kubectl delete secret RELEASE-NAME-postgresql-password

  2. 同じパスワードを使いたい場合は、シークレットを編集し、キーをpostgres-password からpostgresql-passwordに変更してください。 さらに、スーパーユーザーアカウント用のシークレットが必要です。 そのユーザー用のキーをpostgresql-postgres-passwordに追加してください： 

    # Encode the superuser password into base64
echo SUPERUSER_PASSWORD | base64
kubectl edit secret RELEASE-NAME-postgresql-password
# Make the appropriate changes in your EDITOR window

既存サービスの削除

3.0 リリースでは、NGINX Ingress の不変フィールドが更新されます。このため、アップグレード前にまずすべてのサービスを削除する必要があります。詳細は、トラブルシューティングのドキュメントの「Immutable Field Error」、「spec.clusterIP」を参照してください。

  1. 影響を受けるサービスをすべて削除してください。RELEASE_NAME には、helm listからの GitLab リリース名を指定してください： 

    kubectl delete services -lrelease=RELEASE_NAME
注意:LoadBalancer for NGINX Ingressの動的な値が使用されている場合、このChartから変更されます。externalIPの詳細については、グローバルIngress設定のドキュメントを参照してください。 DNSレコードの更新が必要になる場合があります！

GitLabのアップグレード

GitLabのアップグレードは、標準的な手順に従い、以下を追加してください：

バンドルされているPostgreSQLを使用している場合は、アップグレードコマンドで以下のフラグを使用して移行を無効にしてください：

  1. --set gitlab.migrations.enabled=false

バンドルされているPostgreSQLについては、後のステップでデータベースの移行を実行します。

データベースの復元

注意:バンドルされているPostgreSQLチャート（postgresql.install がfalse）を使用していない場合は、この手順を実行する必要はありません。
注意：このスクリプトを正常に実行するには、Bash 4.0以上を使用している必要があります。Bashの連想配列を使用する必要があるからです。

  1. タスクランナーポッドのアップグレードが完了するまで待ちます。 RELEASE_NAME には、以下の GitLab リリースの名前を指定します。helm list 

    kubectl rollout status -w deployment/RELEASE_NAME-task-runner

  2. task-runner ポッドが正常にデプロイされたら、post の手順を実行します：

    このステップでは以下のことを行います：

    1. webservice、sidekiq、gitlab-exporter のデプロイに対してレプリカを 0 に設定します。これにより、バックアップのリストア中に他のアプリケーションがデータベースを変更することを防ぎます。
    2. 前ステージで作成したバックアップからデータベースをリストアします。
    3. 新しいバージョンのデータベース移行を実行します。
    4. 最初のステップからデプロイの一時停止を解除します。 
    # GITLAB_RELEASE should be the version of the chart you are installing, starting with 'v': v3.0.0
curl -s https://gitlab.com/gitlab-org/charts/gitlab/-/raw/${GITLAB_RELEASE}/scripts/database-upgrade | bash -s post

3.0リリースアップグレードプロセスのトラブルシューティング

  • 2.15.xにはバグがあるため、Helm 2.14.3または2.16.1以上を使用していることを確認してください。

  • アップグレード中に何らかの障害が発生した場合は、gitlab-upgrade-check ポッドの説明で詳細を確認するとよいでしょう： 

     kubectl get pods -lrelease=RELEASE,app=gitlab
 kubectl describe pod <gitlab-upgrade-check-pod-full-name>

  • helm upgradeを実行すると、以下のようなエラーが表示されることがあります： 

     Error: kind ConfigMap with the name "gitlab-gitlab-shell-sshd" already exists in the cluster and wasn't defined in the previous release.
 Before upgrading, please either delete the resource from the cluster or remove it from the chart
 Error: UPGRADE FAILED: kind ConfigMap with the name "gitlab-gitlab-shell-sshd" already exists in the cluster and wasn't defined in the previous release.
 Before upgrading, please either delete the resource from the cluster or remove it from the chart

    エラーメッセージはgitlab-redis-healthやgitlab-redis-headlessなど、他のコンフィグマップについても言及しています。この問題を解決するには、3.0リリースのアップグレード手順で述べられているように、サービスが削除されていることを確認してください。その後、エラーメッセージに示されているコンフィグマップもkubectl delete configmap <configmap-name>と一緒に削除してください。