アップグレードガイド
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を新しいバージョンにアップグレードする手順です:
- アップグレードしたいバージョンの変更履歴を確認してください。
- デプロイのドキュメントを順を追って読んでください。
-
で以前の
--set
引数を抽出します。helm get values gitlab > gitlab.yaml
- 設定するすべての値を決定します。
- GitLab Operatorを使用したい場合は、Operatorのインストールで説明されている手順に従ってください。
-
ステップ 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.install
がfalse)を使用していない場合は、この手順を実行する必要はありません。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.install
がfalse)を使用していない場合は、この手順を実行する必要はありません。この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を使用している場合は、アップグレードコマンドで以下のフラグを使用して移行を無効にしてください:
--set gitlab.migrations.enabled=false
バンドルされているPostgreSQLについては、後のステップでデータベースの移行を実行します。
データベースの復元
postgresql.install
がfalse)を使用していない場合は、この手順を実行する必要はありません。-
タスクランナーポッドのアップグレードが完了するまで待ちます。 RELEASE_NAME には、以下の GitLab リリースの名前を指定します。
helm list
kubectl rollout status -w deployment/RELEASE_NAME-task-runner
-
task-runner ポッドが正常にデプロイされたら、
post
の手順を実行します:このステップでは以下のことを行います:
-
webservice
、sidekiq
、gitlab-exporter
のデプロイに対してレプリカを 0 に設定します。これにより、バックアップのリストア中に他のアプリケーションがデータベースを変更することを防ぎます。 - 前ステージで作成したバックアップからデータベースをリストアします。
- 新しいバージョンのデータベース移行を実行します。
- 最初のステップからデプロイの一時停止を解除します。
# 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.install
がfalse)を使用していない場合は、この手順を実行する必要はありません。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 つの手順のいずれかを使用して、データベース パスワードの秘密鍵を更新します:
-
自動生成された 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
-
同じパスワードを使いたい場合は、シークレットを編集し、キーを
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」を参照してください。
-
影響を受けるサービスをすべて削除してください。RELEASE_NAME には、
helm list
からの GitLab リリース名を指定してください:kubectl delete services -lrelease=RELEASE_NAME
LoadBalancer
for NGINX Ingressの動的な値が使用されている場合、このChartから変更されます。externalIP
の詳細については、グローバルIngress設定のドキュメントを参照してください。 DNSレコードの更新が必要になる場合があります!GitLabのアップグレード
GitLabのアップグレードは、標準的な手順に従い、以下を追加してください:
バンドルされているPostgreSQLを使用している場合は、アップグレードコマンドで以下のフラグを使用して移行を無効にしてください:
--set gitlab.migrations.enabled=false
バンドルされているPostgreSQLについては、後のステップでデータベースの移行を実行します。
データベースの復元
postgresql.install
がfalse)を使用していない場合は、この手順を実行する必要はありません。-
タスクランナーポッドのアップグレードが完了するまで待ちます。 RELEASE_NAME には、以下の GitLab リリースの名前を指定します。
helm list
kubectl rollout status -w deployment/RELEASE_NAME-task-runner
-
task-runner ポッドが正常にデプロイされたら、
post
の手順を実行します:このステップでは以下のことを行います:
-
webservice
、sidekiq
、gitlab-exporter
のデプロイに対してレプリカを 0 に設定します。これにより、バックアップのリストア中に他のアプリケーションがデータベースを変更することを防ぎます。 - 前ステージで作成したバックアップからデータベースをリストアします。
- 新しいバージョンのデータベース移行を実行します。
- 最初のステップからデプロイの一時停止を解除します。
# 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>
と一緒に削除してください。