GitLabチャートのアップグレード

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

note
ゼロダウンタイムアップグレードはGitLabチャートでは利用できません。この機能をサポートするための継続的な作業は、GitLab Operator epicで追跡できます。

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

helm get values <release name> を使えば、以前の--set 引数をきれいに取り出すことができます。 これをファイル (helm get values <release name> > gitlab.yaml) に直接書き込めば、このファイルを-f 経由で安全に渡すことができます。このようにhelm upgrade gitlab gitlab/gitlab -f gitlab.yaml.の動作を安全に置き換えることができます。--reuse-values

Chartのバージョン管理とGitLabのバージョン管理のマッピングをご覧ください。

ステップ

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

アップグレードする前に、設定値を振り返って、設定が「過剰」になっていないかどうか確認してください。私たちは、変更された値の小さなリストをメンテナーし、チャートのデフォルトのほとんどを活用することを期待しています。もし、明示的に多くの設定を行った場合は、次のようにしてください:

  • 計算された設定のコピー
  • すべての設定をコピーし、デフォルト値と同じ値を明示的に定義します。

これはアップグレード中にほぼ間違いなくイシューを引き起こします。設定構造がバージョン間で変更されている可能性があり、設定の適用に問題が生じるからです。これを確認する方法については、次の手順で説明します。

GitLab を新しいバージョンにアップグレードする手順は次のとおりです:

  1. アップグレードしたいバージョンの変更履歴を確認してください。
  2. デプロイのドキュメントを順を追って確認します。
  3. 以前に提供した値を抽出します:

    helm get values gitlab > gitlab.yaml
    
  4. アップグレードの際に引き継ぐ必要があるすべての値を決定します。GitLab には合理的なデフォルト値があり、アップグレード中に上記のコマンドからすべての値を渡そうとすることもできますが、Chart のバージョン間で設定が変更されているシナリオを作成する可能性があり、きれいにマッピングできないかもしれません。私たちは、明示的に設定したい最小限の値のセットを保持し、アップグレードの過程でそれらを渡すことをお勧めします。
  5. 前のステップで抽出した値でアップグレードを実行します:

    helm upgrade gitlab gitlab/gitlab \
      --version <new version> \
      -f gitlab.yaml \
      --set gitlab.migrations.enabled=true \
      --set ...
    

データベースのメジャーアップグレード時には、gitlab.migrations.enabledfalse に設定するようお願いしています。今後のアップデートのために、明示的にtrue に戻すようにしてください。

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

note
バンドルされているPostgreSQLチャートを使用していない場合(postgresql.install がfalse)、この手順を実行する必要はありません。

バンドルされているPostgreSQLをバージョン13にアップグレードしてください。

PostgreSQL 13はGitLab 14.1以降でサポートされています。PostgreSQL 13ではパフォーマンスが大幅に改善されました。

バンドルされているPostgreSQLをバージョン13にアップグレードするには、以下の手順が必要です:

  1. 既存のデータベースを準備します。
  2. 既存の PostgreSQL データを削除します。
  3. postgresql.image.tag の値を13.6.0 に更新し、Chart を再インストールして新しい PostgreSQL 13 データベースを作成します。
  4. データベースをリストアしてください。

バンドルされているPostgreSQLをバージョン12にアップグレードします。

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

バンドルされているPostgreSQLをバージョン11にアップグレードします。

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

バージョン7.0へのアップグレード

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

7.0.x リリースでは、アップグレードを実行するために手動手順が必要になる場合があります。

  • クラスタ内Redisサービスを提供するためにバンドルされたbitnami/Redis サブチャートを使用している場合 - GitLabチャートのバージョン7.0にアップグレードする前に、Redis用のStatefulSetを手動で削除する必要があります。以下のUpgrade the bundled Redis sub-chartの設定に従ってください。

バンドルされているRedisサブチャートの更新

GitLab チャートのリリース 7.0 では、バンドルされているbitnami/Redis サブチャートを、以前インストールされていた11.3.4 から16.13.2 に更新しました。matchLabels の変更がサブチャートのredis-master StatefulSet に適用されたため、StatefulSet を手動で削除せずにアップグレードすると、次のエラーが発生します:

Error: UPGRADE FAILED: cannot patch "gitlab-redis-master" with kind StatefulSet: StatefulSet.apps "gitlab-redis-master" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy' and 'minReadySeconds' are forbidden

RELEASE-redis-master の StatefulSet を削除するには、次の手順に従います:

  1. webservicesidekiqkasgitlab-exporter のデプロイについて、0 にレプリカをスケールダウンします:

    kubectl scale deployment --replicas 0 --selector 'app in (webservice, sidekiq, kas, gitlab-exporter)' --namespace <namespace>
    
  2. RELEASE-redis-master StatefulSetを削除します:

    kubectl delete statefulset RELEASE-redis-master --namespace <namespace>
    
    • <namespace> はGitLab Chartをインストールしたネームスペースに置き換えてください。

それから標準のアップグレード手順に従ってください。Helm がどのように変更をマージするかによって、ステップ 1 でスケールダウンしたデプロイを手動でスケールアップする必要があるかもしれません。

アップグレードにはglobal.redis.password

global.redis.password の使用による設定タイプの衝突を緩和するため、global.redis.password の使用を非推奨とし、global.redis.auth を使用することにしました。

helm upgrade 、非推奨であることが表示されるだけでなく、次のような警告メッセージが表示されます:

coalesce.go:199: warning: destination for password is a table. Ignoring non-table value

これは、値ファイルにglobal.redis.password を設定していることを示しています。

バージョン6.0へのアップグレード

caution
5.x バージョンの Chart から最新の6.0 リリースにアップグレードする場合、アップグレードを動作させるために、まず5.10.x パッチの最新リリースに更新する必要があります。6.0 のリリースノートには、サポートされているアップグレードパスが記載されています。

6.0 リリースにアップグレードするには、まず最新の5.10.x パッチリリースにする必要があります。6.0 では、手動による追加の変更は必要ありませんので、通常のリリースアップグレードの手順に従ってください。

バージョン5.9へのアップグレード

Sidekiq ポッドが準備完了になりません。

5.9.x にアップグレードすると、Sidekiqポッドが準備完了にならない場合があります。ポッドは起動し、正常に動作しているように見えますが、デフォルトのメトリクス・エンドポイント・ポート(metrics.port )である3807 をリッスンすることはありません。その結果、Sidekiqポッドは準備完了とは見なされません。

これは、管理エリアから解決できます:

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 設定 > メトリクスとプロファイリングを選択します。
  4. メトリクス - Prometheus」を展開します。
  5. Enable health and performance metrics]エンドポイントが有効になっていることを確認します。
  6. 影響を受けるポッドを再起動します。

このシナリオについては、クローズド・イシューに追加情報があります。

バージョン5.5へのアップグレード

task-runner チャートはtoolbox改名され、5.5.0 で削除されました。そのため、設定にある のtask-runner 名前は task-runnertask-runner toolbox. toolbox task-runnerChart に変更するtask-runner 必要が task-runnerあります。task-runner toolboxバージョン5.5以降では、 toolbox task-runnerこのtask-runner チャートをtoolbox使用 toolbox task-runnertask-runner 、バージョン5.4以前では、この task-runnerチャートを使用してください。

オブジェクトストレージの秘密が見つからないエラー

5.5以降にアップグレードすると、以下のようなエラーが発生する場合があります:

Error: UPGRADE FAILED: execution error at (gitlab/charts/gitlab/charts/toolbox/templates/deployment.yaml:227:23): A valid backups.objectStorage.config.secret is needed!

エラーで言及されているシークレットがすでに存在し、正しい場合、このエラーは、新しいtoolbox ではなくtask-runner をまだ参照しているオブジェクトストレージ設定値があるためと考えられます。設定内のtask-runner の名前をtoolbox に変更してください。

エラー・メッセージの明確化に関するイシューがオープンになっています。

バージョン5.0へのアップグレード

caution
4.x バージョンの Chart から最新の5.0 リリースにアップグレードする場合、アップグレードを動作させるために、まず最新の4.12.x パッチリリースにアップデートする必要があります。5.0 のリリースノートには、サポートされるアップグレードのパスが記述されています。

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

caution
アップグレードを行う前にバックアップを取ることを忘れないでください。これらの手順をドキュメント通りに実行しないと、データベースを失う可能性があります。別のバックアップがあることを確認してください。

外部の PostgreSQL データベースを使用している場合は、まずデータベースをバージョン 12 以上にアップグレードしてください。その後、標準のアップグレード手順に従ってください。

バンドルされている PostgreSQL データベースを使用している場合は、バンドルされているデータベースのアップグレード手順に従ってください。

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

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

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

バージョン4.0へのアップグレード

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

caution
アップグレードを行う前にバックアップを取ることを忘れないでください。これらの手順をドキュメント通りに実行しないと、データベースを失う可能性があります。別のバックアップがあることを確認してください。

外部の PostgreSQL データベースを使用している場合は、まずデータベースをバージョン 11 以上にアップグレードしてください。その後、標準のアップグレード手順に従ってください。

バンドルされている PostgreSQL データベースを使用している場合は、バンドルされているデータベースのアップグレード手順に従ってください。

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

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

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

4.8: リポジトリのデータが失われたようです。

Praefect のチャートは、本番使用にはまだ適していません。

Chartのバージョン4.8(GitLab 13.8)にアップグレードする前にPraefectを有効にした場合、GitalyのStatefulSet名に仮想ストレージ名が含まれるようになったことに注意してください。

Praefectチャートのバージョン4.8では、複数の仮想ストレージを指定する機能が追加されたため、StatefulSet名を変更する必要があります。

既存のPraefectが管理するGitaly StatefulSet名(したがって、関連するPersistentVolumeClaims)も変更され、リポジトリデータが失われたように見えます。

アップグレードする前に、以下を確認してください:

  • すべてのリポジトリが Gitaly クラスター間で同期しており、アップグレード中に GitLab が使用されていないこと。リポジトリが同期しているかどうかを確認するには、Praefectポッドの1つで以下のコマンドを実行します:

     /usr/local/bin/praefect -config /etc/gitaly/config.toml dataloss
    
  • 完全でテスト済みのバックアップがあります。

リポジトリ・データは、既存のPersistentVolumeClaimを以前のPersistentVolumeに再接続するためのガイダンスが記載されている「永続ボリュームの管理」のドキュメントに従ってリストアできます。

このプロセスの重要な手順は、古い永続ボリュームのpersistentVolumeReclaimPolicyRetainに設定することです。 この手順を怠ると、実際のデータ損失が発生する可能性が高くなります。

ドキュメントをレビューしたところ、関連するイシューの1つのコメントに、スクリプトによる手順の要約がありました。

PersistentVolumesを再接続すると、Praefectコンテナで以下を実行したように、すべてのリポジトリがPraefectによってread-only

praefect -config /etc/gitaly/config.toml dataloss

すべてのGitリポジトリが古い永続ボリューム間で同期している場合は、各リポジトリのaccept-dataloss

これが Praefect を修正する最善の方法であることを検証するために、イシューを公開しています。