アップグレード前に

GitLabインスタンスをアップグレードする前に、以下を実行する必要があります:

1. アップグレードに備えるために、アップグレード前の情報を収集します。
2. GitLab自体をアップグレードする前に、アップグレード前の手順を実行します。

アップグレード前の情報を収集する

アップグレードを計画する際は、以下を行います:

1. GitLabのリリースおよびメンテナンスポリシーを確認してください。
2. 互換性を確保するため、アップグレード前に、さまざまなバージョンのGitLabに関するGitLabのリリースノートを参照してください。
3. 該当する場合は、GitLab対象バージョンとのOSの互換性を確認してください。
4. Geoを使用している場合:
   • Geoアップグレードドキュメントを確認します。
   • GitLabのアップグレードに関する注記で、Geo固有の情報を確認します。
   • データベースをアップグレードする場合は、Geo固有の手順を確認してください。
   • 各Geoサイト（プライマリおよび各セカンダリ）のアップグレードおよびロールバック計画を作成します。
5. 必要なアップグレード停止を含め、インスタンスに適したアップグレードパスを決定します。アップグレードストップにより、複数のアップグレードを実行するよう求められる場合があります。
6. 以下を記述したアップグレード計画を作成します:
   • 可能な場合、ゼロダウンタイムアップグレードを含め、インスタンスをアップグレードするために実行する手順。
   • 必要な場合にGitLabをロールバックする方法を含め、アップグレードがスムーズに進まない場合に実行する手順。

アップグレード前の情報をすべて収集したら、アップグレード前の手順の実行に進むことができます。

ロールバック計画とバックアップを作成する

アップグレード中に問題が発生する可能性があるため、ロールバック計画を立てることが重要です。適切なロールバック計画を作成することで、インスタンスを最後に動作していた状態に戻すための明確な道筋ができます:

• インスタンスをバックアップするプロセス。
• インスタンスを復元するプロセス。

ロールバックプランは、実際に必要になる前にテストする必要があります。ロールバックに必要な手順の概要については、以前のGitLabのバージョンにロールバックするを参照してください。

GitLabのバックアップを作成します。

アップグレードで問題が発生した場合に、GitLabをロールバックできるようにするには、次のいずれかの操作を行います:

• GitLabのバックアップを作成します。インストールの方法に基づいて指示に従い、シークレットと設定ファイルを必ずバックアップしてください。
• インスタンスのスナップショットを作成します。インスタンスがマルチノードインストールされている場合は、すべてのノードのスナップショットを作成する必要があります。このプロセスは、GitLabサポートの範囲外です。

GitLabをロールバックする

本番環境を模倣したテスト環境がある場合は、復元をテストして、すべてが期待どおりに動作することを確認してください。

GitLabのバックアップを復元するには:

1. 復元の前提条件を参照してください。最も重要なことは、バックアップされたGitLabインスタンスと新しいGitLabインスタンスのバージョンが同じである必要があります。
2. インストールの方法に基づいて指示に従って、GitLabを復元します。
3. シークレットと設定ファイルも復元されていることを確認してください。

スナップショットから復元する場合は、その方法をすでに知っている必要があります。このプロセスは、GitLabサポートの範囲外です。

アップグレードを行う前に、事前アップグレード手順を実行します。

アップグレードを実行する直前に、以下を行います:

1. 最初にテスト環境でアップグレードをテストし、計画外の停止や長期ダウンタイムのリスクを軽減するためにロールバック計画を立ててください。
2. アップグレードヘルスチェックを実行します。
3. 使用するオプション機能のアップグレードを実行します。

アップグレードヘルスチェックを実行する

アップグレードの直前と直後に、GitLabの主要コンポーネントが動作していることを確認するために、アップグレードヘルスチェックを実行します:

1. 一般的な設定を確認します:

   sudo gitlab-rake gitlab:check

2. すべてのバックグラウンドデータベース移行のステータスを確認します。すべての移行は、各アップグレードの前に完了する必要があります。バックグラウンド移行を完了する時間を確保するために、メジャーリリースとマイナーリリースの間でアップグレードを分散させる必要があります。

3. 暗号化されたデータベース値が復号化できることを確認します:

   sudo gitlab-rake gitlab:doctor:secrets

4. GitLabのUIで、以下を確認します:

   • ユーザーがサインインできる。
   • プロジェクトリストが表示される。
   • プロジェクトのイシューとマージリクエストにアクセスできる。
   • ユーザーがGitLabからリポジトリを複製できる。
   • ユーザーがGitLabにコミットをプッシュできる。

5. GitLab CI/CDでは、以下を確認します:

   • Runnerがジョブを取得する。
   • Dockerイメージをレジストリからプッシュおよびプルできる。

6. Geoを使用している場合は、プライマリサイトと各セカンダリサイトで関連するチェックを実行します:

   sudo gitlab-rake gitlab:geo:check

7. Elasticsearchを使用している場合は、検索が成功したことを確認します。

問題が発生した場合は、サポートにお問い合わせください。

オプション機能のアップグレード

GitLabインスタンスの設定方法によっては、GitLabをアップグレードする前に、これらの追加手順を実行する必要がある場合があります:

1. 外部Gitalyサーバーを使用している場合は、GitLab自体をアップグレードする前に、Gitalyサーバーを新しいバージョンにアップグレードします。これにより、アプリケーションサーバー上のgRPCクライアントが、古いGitalyバージョンがサポートしていないRPCsを送信するのを防ぎます。

2. KubernetesクラスターがGitLabに接続されている場合は、新しいGitLabバージョンに合わせてKubernetes向けGitLabエージェントをアップグレードします。

3. 高度な検索（Elasticsearch）を使用している場合は、保留中の移行の確認によって、高度な検索移行が完了したことを確認します。

   GitLabをアップグレードした後、新しいバージョンが互換性を損なう場合は、Elasticsearchをアップグレードする必要があるかもしれません。Elasticsearchの更新はGitLabサポートの対象外です。

CI/CDパイプラインとジョブを一時停止する

ほとんどの種類のGitLabインスタンスのアップグレード中は、CI/CDパイプラインとジョブを一時停止する必要があります。

GitLab Runnerがジョブを処理している間にGitLabインスタンスをアップグレードすると、トレーシングの更新が失敗します。GitLabがオンラインに戻ると、トレース更新は自動修復されるはずです。トレースの更新が自己修復しない場合、エラーに応じて、GitLab Runnerはジョブ処理を再試行するか、終了します。

GitLab Runnerはジョブアーティファクトのアップロードを3回試行し、その後ジョブが失敗します。

CI/CDパイプラインとジョブを一時停止するには、次のようにします:

1. Runnerを一時停止します。

2. 次の内容を/etc/gitlab/gitlab.rbファイルに追加して、新しいジョブが開始されないようにブロックします:

   nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"

3. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

4. すべてのジョブが完了するまで待ちます。

GitLabのアップグレードが完了したら、次のようにします:

1. Runnerの一時停止を解除します。
2. 以前の/etc/gitlab/gitlab.rbの変更を元に戻して、新しいジョブが開始されないようにブロックします。

サポートと連携する

サポートと連携してアップグレードプランをレビューする場合は、レビューと次の質問への回答を文書化して共有してください:

• GitLabはどのようにインストールされていますか？
• ノードのオペレーティングシステムは何ですか？サポートされているプラットフォームをチェックして、新しい更新が利用できることを確認してください。
• シングルノードのセットアップですか、それともマルチノードのセットアップですか？マルチノードの場合は、各ノードに関するアーキテクチャの詳細を文書化して共有してください。どの外部コンポーネントが使用されていますか？たとえば、Gitaly、PostgreSQL、またはRedisですか？
• Geoを使用していますか？使用している場合は、各セカンダリサイトに関するアーキテクチャの詳細を文書化して共有してください。
• セットアップで他にどのようなユニークな点または興味深い点が重要になる可能性がありますか？
• 現在のバージョンのGitLabで既知の問題が発生していますか？

サポートを受ける

アップグレード中に問題が発生した場合は、次のようにします:

1. エラーをコピーして、後で分析するためにログを収集します。データの収集には次のツールが役立ちます:
   • gitlabsos: LinuxパッケージまたはDockerを使用してGitLabをインストールした場合。
   • kubesos: Helm Chartを使用してGitLabをインストールした場合。
2. 最後に動作していたバージョンにロールバックします。

サポート:

• GitLabサポートにお問い合わせください。担当のカスタマーサクセスマネージャーがいる場合は、そちらにもお問い合わせください。
• 問題の状態が対象となる 、かつプランに緊急サポートが含まれている場合は、緊急チケットを作成してください。