正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

ダウンタイムなしでマルチノードインスタンスをアップグレードする

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab Self-Managed

ゼロダウンタイムでマルチノードのGitLab環境をアップグレードするプロセスでは、アップグレードの順序に従って、各ノードを順番に処理します。ロードバランサーとHAメカニズムにより、各ノードの停止が適切に処理されます。

ゼロダウンタイムでのアップグレードを開始する前に、ダウンタイムのオプションを検討してください。

はじめに

アップグレードの一環としてゼロダウンタイムを達成することは、分散アプリケーションにとっては特に困難です。このドキュメントは、HAの参照アーキテクチャに対して提供されているとおりにテストされており、事実上、観測可能なダウンタイムは発生しませんでした。ただし、実際の結果は、特定のシステム構成によって異なる可能性があることに注意してください。

さらに信頼性を高めるために、特定のロードバランサーまたはインフラストラクチャ機能を使用してノードを手動でドレインするなど、高度な手法で成功を収めているお客様もいます。これらの手法は、基盤となるインフラストラクチャの機能に大きく依存します。

詳細については、GitLabの担当者またはサポートチームにお問い合わせください。

要件

ゼロダウンタイムアップグレードプロセスには、ロードバランシングと、次のように設定された利用可能なHAメカニズムを備えたLinuxパッケージで構築されたマルチノードのGitLab環境が必要です:

  • ヘルスチェック（/-/readiness）エンドポイントに対して有効になっているヘルスチェックを使用して、GitLabアプリケーションノード用に構成された外部ロードバランサー。
  • TCPヘルスチェックが有効になっているPgBouncerおよびPraefectコンポーネント用に構成された内部ロードバランサー。
  • 存在する場合は、Consul、Postgres、およびRedisコンポーネント用に構成されたHAメカニズム。

ゼロダウンタイムアップグレードを行うには、以下が必要です:

  • 一度に1つのマイナーリリースをアップグレードします。そのため、16.1から16.2へはアップグレードできますが、16.3へはアップグレードできません。リリースをスキップすると、データベースの変更が間違った順序で実行され、データベーススキーマが破損した状態になる可能性があります。
  • post-deployment移行を使用してください。

考慮事項

ゼロダウンタイムアップグレードを検討する場合は、次の点に注意してください:

  • ほとんどの場合、パッチリリースが最新でない場合は、パッチリリースから次のマイナーリリースに安全にアップグレードできます。たとえば、16.3.2から16.4.1へのアップグレードは、16.3.3がリリースされている場合でも安全であるはずです。アップグレードパスに関連するバージョン固有のアップグレードノートを確認し、必要なアップグレード停止を認識しておく必要があります:
  • 一部のリリースには、バックグラウンド移行が含まれている場合があります。これらの移行は、Sidekiqによってバックグラウンドで実行され、多くの場合、データを移行するために使用されます。バックグラウンド移行は、毎月のリリースでのみ追加されます。
    • 特定のメジャーまたはマイナーリリースでは、一連のバックグラウンド移行を完了する必要がある場合があります。これにより（上記の条件が満たされている場合）ダウンタイムは不要になりますが、メジャーまたはマイナーリリースをアップグレードするたびに、バックグラウンド移行が完了するまで待つ必要があります。
    • これらの移行を完了するために必要な時間は、background_migrationキュー内のジョブを処理できるSidekiqワーカーの数を増やすことで短縮できます。このキューのサイズを確認するには、アップグレードする前にバックグラウンド移行を確認してください。
  • 正常な再読み込みメカニズムにより、Gitalyのゼロダウンタイムアップグレードを実行できます。Gitalyクラスター（Praefect）コンポーネントも、ダウンタイムなしで直接アップグレードできます。ただし、Linuxパッケージは、PraefectデータベースのHAまたはゼロダウンタイムサポートを提供していません。ダウンタイムを回避するには、サードパーティのデータベースソリューションが必要です。
  • PostgreSQLのメジャーバージョンのアップグレードは別のプロセスであり、ゼロダウンタイムアップグレードの対象ではありません。小規模なアップグレードは対象となります。
  • ゼロダウンタイムアップグレードは、Linuxパッケージでデプロイした、注記されているGitLabコンポーネントでサポートされています。AWS Amazon Relational Database ServiceのPostgreSQLやGCP MemorystoreのRedisなど、サポートされているサードパーティサービスを介して特定のコンポーネントをデプロイしている場合は、それらのサービスのアップグレードを標準プロセスに従って個別に行う必要があります。
  • 一般的なガイドラインとして、データの量が多いほど、アップグレードの完了に必要な時間が長くなります。テストでは、10 GB未満のデータベースは通常1時間以上かかることはありませんが、結果は異なる場合があります。

アップグレードの順序

ゼロダウンタイムでアップグレードするコンポーネントの順序については、奥から手前に向かうアプローチを採用する必要があります:

  1. ステートフルバックエンド
  2. バックエンドの依存
  3. フロントエンド

デプロイの順序は変更できますが、GitLabアプリケーションコード（RailsやSidekiqなど）を実行するコンポーネントはまとめてデプロイする必要があります。可能であれば、メジャーリリースのバージョンアップグレードで導入された変更に対する依存関係がないため、サポートインフラストラクチャを個別にアップグレードしてください。

次の順序でGitLabコンポーネントをアップグレードする必要があります:

  1. Consul
  2. PostgreSQL
  3. PgBouncer
  4. Redis
  5. Gitaly
  6. Praefect
  7. Rails
  8. Sidekiq

Consul、PostgreSQLデータベース、PgBouncer、およびRedisノードのアップグレード

Consul 、PostgreSQLデータベース 、PgBouncer 、およびRedisコンポーネントはすべて、ダウンタイムなしでアップグレードするための同じ基盤となるプロセスに従います。

アップグレードを実行する各コンポーネントのノードで:

  1. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. GitLabパッケージをアップグレードします。

  3. 再構成して再起動し、最新のコードを配置します:

    sudo gitlab-ctl reconfigure

    最初にConsulクライアントを再起動し、次に他のすべてのサービスを再起動して、PostgreSQLデータベースのフェイルオーバーが正常に行われるようにします:

    sudo gitlab-ctl restart consul
sudo gitlab-ctl restart-except consul
    sudo gitlab-ctl restart

Gitalyノードのアップグレード

Gitalyは、アップグレードに関しては同じコアプロセスに従いますが、Gitalyプロセス自体は、可能な限り早く正常に再読み込みするための組み込みプロセスがあるため、再起動されないという重要な違いがあります。他のコンポーネントは引き続き再起動する必要があります。

アップグレードプロセスは、新しいGitalyプロセスへの正常な引き渡しを試みます。アップグレード前に開始された既存の長時間実行されているGitリクエストは、この引き渡しが発生すると最終的にドロップされる可能性があります。将来的には、この機能が変更される可能性があります。詳細については、このEpicを参照してください。

このプロセスは、Gitalyシャーディングおよびクラスターセットアップの両方に適用されます。アップグレードを実行するには、各Gitalyノードで次の手順を順番に実行します:

  1. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. GitLabパッケージをアップグレードします。

  3. 最新のコードを配置し、Gitalyに次の機会に正常に再読み込みするように指示するには、reconfigureコマンドを実行します:

    sudo gitlab-ctl reconfigure

  4. 最後に、Gitalyはデプロイされている他のコンポーネントを正常に再読み込みしますが、再起動は依然として必要です:

    # Get a list of what other components have been deployed beside Gitaly
sudo gitlab-ctl status

# Restart each component except Gitaly. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

Gitalyクラスター（Praefect）ノードのアップグレード

Gitalyクラスター（Praefect）セットアップの場合、正常な再読み込みを使用して、同様の方法でPraefectをデプロイおよびアップグレードする必要があります。

アップグレードプロセスは、新しいPraefectプロセスへの正常な引き渡しを試みます。アップグレード前に開始された既存の長時間実行されているGitリクエストは、この引き渡しが発生すると最終的にドロップされる可能性があります。将来的には、この機能が変更される可能性があります。詳細については、このEpicを参照してください。

このセクションでは、Praefectコンポーネントのみに焦点を当てており、必須のPostgreSQLデータベースには焦点を当てていません。GitLab LinuxパッケージはHAを提供していません。したがって、Praefectデータベースのゼロダウンタイムサポートも提供していません。ダウンタイムを回避するには、サードパーティのデータベースソリューションが必要です。

Praefectは、既存のデータをアップグレードするためにデータベース移行も実行する必要があります。競合を避けるために、移行は1つのPraefectノードでのみ実行する必要があります。これを行うには、移行を実行する特定のノードをデプロイノードとして指定します。これは、以下の手順でPraefectデプロイノードと呼ばれます:

  1. Praefectデプロイノードで:

    1. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. GitLabパッケージをアップグレードします。

    3. praefect['auto_migrate'] = trueが/etc/gitlab/gitlab.rbで設定されていることを確認して、データベース移行が実行されるようにします。

    4. reconfigureコマンドを実行して、最新のコードを配置し、Praefectデータベース移行を適用して正常に再起動します:

      sudo gitlab-ctl reconfigure

  2. すべて残りのPraefectノード:

    1. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    2. GitLabパッケージをアップグレードします。

    3. reconfigureがデータベース移行を自動的に実行しないようにするには、praefect['auto_migrate'] = falseが/etc/gitlab/gitlab.rbで設定されていることを確認してください。

    4. reconfigureコマンドを実行して、最新のコードを配置し、正常に再起動します:

      sudo gitlab-ctl reconfigure

  3. 最後に、Praefectは正常に再読み込みされますが、デプロイされている他のコンポーネントは引き続き再起動が必要です。すべてのPraefectノード:

    # Get a list of what other components have been deployed beside Praefect
sudo gitlab-ctl status

# Restart each component except Praefect. Example given for Consul, Node Exporter and Logrotate
sudo gitlab-ctl restart consul node-exporter logrotate

GitLabアプリケーション（Rails）ノードのアップグレード

WebサーバーとしてのRailsは、主にPuma、Workhorse、およびNGINXで構成されています。

これらの各コンポーネントには、ライブアップグレードの実行に関して異なる動作があります。Pumaは正常な再読み込みを許可できますが、Workhorseは許可しません。最良のアプローチは、ロードバランサーを使用するなど、他の手段でノードを正常にドレインすることです。また、正常なシャットダウン機能を使用して、ノードでNGINXを使用することによってこれを行うこともできます。このセクションでは、NGINXアプローチについて説明します。

上記の他に、Railsはメインデータベース移行を実行する必要がある場所です。Praefectと同様に、最良のアプローチはデプロイノードを使用することです。PgBouncerが現在使用されている場合は、データベース移行の実行を試みるときに、Railsがアドバイザリロックを使用するため、これも回避する必要があります。これにより、同じデータベースで同時移行が実行されるのを防ぎます。これらのロックはトランザクション間で共有されないため、トランザクションプールモードでPgBouncerを使用してデータベース移行を実行すると、ActiveRecord::ConcurrentMigrationErrorやその他の問題が発生します。

  1. Railsデプロイノードの場合:

    1. トラフィックのノードを正常にドレインします。これはさまざまな方法で実行できますが、1つのアプローチは、QUITシグナルを送信してサービスを停止することにより、NGINXを使用することです。例として、次のシェルスクリプトを使用してこれを行うことができます:

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. GitLabパッケージをアップグレードします。

    4. /etc/gitlab/gitlab.rb設定ファイルでgitlab_rails['auto_migrate'] = trueを設定することにより、通常の移行が実行されるように構成します。

      • デプロイノードが現在PgBouncerを介してデータベースに接続している場合は、回避し、移行を実行する前にデータベースリーダーに直接接続する必要があります。
      • データベースリーダーを見つけるには、任意のデータベースノードで次のコマンドを実行します - sudo gitlab-ctl patroni members。

    5. 通常の移行を実行し、最新のコードを配置します:

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure

    6. 後でデプロイ後の移行を実行するために戻ってくるので、このノードは現状のままにしておきます。

  2. すべての他のRailsノードで順番に:

    1. トラフィックのノードを正常にドレインします。これはさまざまな方法で実行できますが、1つのアプローチは、QUITシグナルを送信してサービスを停止することにより、NGINXを使用することです。例として、次のシェルスクリプトを使用してこれを行うことができます:

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    3. GitLabパッケージをアップグレードします。

    4. reconfigureがデータベース移行を自動的に実行しないようにするには、gitlab_rails['auto_migrate'] = falseが/etc/gitlab/gitlab.rbで設定されていることを確認してください。

    5. reconfigureコマンドを実行して、最新のコードを配置し、再起動します:

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  3. Railsデプロイノードで、デプロイ後の移行を実行します:

    1. デプロイノードがデータベースリーダーを直接指していることを確認します。ノードが現在PgBouncerを介してデータベースに接続している場合は、回避し、移行を実行する前にデータベースリーダーに直接接続する必要があります。

      • データベースリーダーを見つけるには、任意のデータベースノードで次のコマンドを実行します - sudo gitlab-ctl patroni members。

    2. post-deployment移行を実行します:

      sudo gitlab-rake gitlab:db:configure

      このタスクは、ClickHouse移行も実行し、スキーマを読み込むことで、その状態に基づいてデータベースを構成します。

    3. /etc/gitlab/gitlab.rb設定ファイルでgitlab_rails['auto_migrate'] = falseを設定することにより、構成を通常に戻します。

      • PgBouncerを使用している場合は、データベース構成が再びそれを指すように設定してください

    4. 再構成をもう一度実行して、通常の構成を再適用し、再起動します:

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiqノードのアップグレード

Sidekiqは、ダウンタイムなしでアップグレードするために、他のプロセスと同じ基盤となるプロセスに従います。

アップグレードを実行するには、各コンポーネントノードで次の手順を順番に実行します:

  1. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

    sudo touch /etc/gitlab/skip-auto-reconfigure

  2. GitLabパッケージをアップグレードします。

  3. reconfigureコマンドを実行して、最新のコードを配置し、再起動します:

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

マルチノードGeoインスタンスのアップグレード

  • プラン: Premium、Ultimate
  • 提供形態: GitLab Self-Managed

このセクションでは、GeoでライブGitLab環境デプロイをアップグレードするために必要な手順について説明します。

全体として、このアプローチは通常のプロセスとほぼ同じですが、セカンダリサイトごとに追加の手順が必要です。必要な順序は、最初にプライマリをアップグレードし、次にセカンダリをアップグレードすることです。すべてのセカンダリが更新されたら、プライマリでデプロイ後の移行も実行する必要があります。

要件と考慮事項は、GeoでライブGitLab環境をアップグレードする場合にも適用されます。

プライマリサイト

プライマリサイトのアップグレードプロセスは、セカンダリがすべて更新されるまで、デプロイ後の移行を実行しないことを除き、通常のプロセスと同じです。

説明されているプライマリサイトと同じ手順を実行しますが、デプロイ後の移行の実行のRailsノードの手順で停止します。

セカンダリサイト

セカンダリサイトのアップグレードプロセスは、Railsノードを除き、通常のプロセスと同じ手順に従います。アップグレードプロセスは、プライマリサイトとセカンダリサイトの両方で同じです。ただし、セカンダリサイトのRailsノードに対して、次の追加手順を実行する必要があります。

Rails

  1. Railsデプロイノードの場合:

    1. トラフィックのノードを正常にドレインします。これはさまざまな方法で実行できますが、1つのアプローチは、QUITシグナルを送信してサービスを停止することにより、NGINXを使用することです。例として、次のシェルスクリプトを使用してこれを行うことができます:

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursorプロセスを停止して、別のノードへのフェイルオーバーを確実にします:

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. GitLabパッケージをアップグレードします。

    5. プライマリサイトのRailsノードから/etc/gitlab/gitlab-secrets.jsonファイルをセカンダリサイトのRailsノードにコピーします（異なる場合）。ファイルは、サイトのすべてのノードで同じである必要があります。

    6. /etc/gitlab/gitlab.rb設定ファイルで、gitlab_rails['auto_migrate'] = falseとgeo_secondary['auto_migrate'] = falseを設定して、移行が自動的に実行されるように設定されていないことを確認します。

    7. reconfigureコマンドを実行して、最新のコードを配置し、再起動します:

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

    8. 通常のGeo Tracking移行を実行し、最新のコードを配置します:

      sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-rake db:migrate:geo

  2. すべての他のRailsノードで順番に:

    1. トラフィックのノードを正常にドレインします。これはさまざまな方法で実行できますが、1つのアプローチは、QUITシグナルを送信してサービスを停止することにより、NGINXを使用することです。例として、次のシェルスクリプトを使用してこれを行うことができます:

      # Send QUIT to NGINX master process to drain and exit
NGINX_PID=$(cat /var/opt/gitlab/nginx/nginx.pid)
kill -QUIT $NGINX_PID

# Wait for drain to complete
while kill -0 $NGINX_PID 2>/dev/null; do sleep 1; done

# Stop NGINX service to prevent automatic restarts
gitlab-ctl stop nginx

    2. Geo Log Cursorプロセスを停止して、別のノードへのフェイルオーバーを確実にします:

      gitlab-ctl stop geo-logcursor

    3. /etc/gitlab/skip-auto-reconfigureに空のファイルを作成します。これにより、gitlab-ctl reconfigureの実行によるアップグレードが防止されます。デフォルトでは、GitLabが自動的に停止し、すべてのデータベース移行が実行され、GitLabが再起動されます:

      sudo touch /etc/gitlab/skip-auto-reconfigure

    4. GitLabパッケージをアップグレードします。

    5. /etc/gitlab/gitlab.rb設定ファイルで、gitlab_rails['auto_migrate'] = falseとgeo_secondary['auto_migrate'] = falseを設定して、移行が自動的に実行されるように設定されていないことを確認します。

    6. reconfigureコマンドを実行して、最新のコードを配置し、再起動します:

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Sidekiq

メインプロセスに続いて、残りの作業はSidekiqのアップグレードです。

メインセクションで説明されているのと同じ方法でSidekiqをアップグレードします。

post-deployment移行

最後に、プライマリサイトに戻り、デプロイ後の移行を実行してアップグレードを完了します:

  1. プライマリサイトのRailsデプロイノードで、デプロイ後の移行を実行します:

    1. デプロイノードがデータベースリーダーを直接指していることを確認します。ノードが現在PgBouncerを介してデータベースに接続している場合は、回避し、移行を実行する前にデータベースリーダーに直接接続する必要があります。

      • データベースリーダーを見つけるには、任意のデータベースノードで次のコマンドを実行します - sudo gitlab-ctl patroni members。

    2. post-deployment移行を実行します:

      sudo gitlab-rake gitlab:db:configure

    3. Geo設定と依存関係を確認します

      sudo gitlab-rake gitlab:geo:check

    4. /etc/gitlab/gitlab.rb設定ファイルでgitlab_rails['auto_migrate'] = falseを設定することにより、構成を通常に戻します。

      • PgBouncerを使用している場合は、データベース構成が再びそれを指すように設定してください

    5. 再構成をもう一度実行して、通常の構成を再適用し、再起動します:

      sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

  2. セカンダリサイトのRailsデプロイノードで、デプロイ後のGeo Tracking移行を実行します:

    1. デプロイ後のGeo Tracking移行を実行します:

      sudo gitlab-rake db:migrate:geo

    2. Geoステータスを確認します:

      sudo gitlab-rake geo:status