失敗しないためのGitLabアップグレード手順

By /

失敗しないためのGitLabアップグレード手順 – 徹底ガイド

はじめに

DevOpsプラットフォームとして世界中で利用されているGitLabは、活発な開発が行われており、セキュリティの向上、新機能の追加、パフォーマンスの改善が継続的に行われています。これらの恩恵を受けるためには、GitLabインスタンスを定期的に最新バージョンにアップグレードすることが不可欠です。しかし、GitLabのアップグレードは、その複雑なアーキテクチャや依存関係、組織固有のカスタマイズなどにより、時に困難を伴い、失敗するリスクも存在します。アップグレードの失敗は、予期せぬダウンタイム、データの損失、機能不全を引き起こし、開発・運用プロセスに深刻な影響を与えかねません。

本記事は、GitLabのアップグレードを「失敗しない」ことを最大の目標とし、アップグレードプロセスの全体像、各段階での注意点、具体的な手順、潜在的な問題への対処法を詳細に解説するものです。特に、多くのユーザーが利用しているOmnibus Package（Linuxパッケージ）を用いたアップグレードを中心に説明します。この記事を読むことで、計画段階から実行、そして事後対応まで、自信を持ってGitLabのアップグレードに臨めるようになることを目指します。

この記事の対象読者:

  • GitLabのシステム管理者、運用担当者
  • GitLabアップグレードの経験が浅い方、あるいは初めて行う方
  • 過去にGitLabアップグレードで苦労した経験がある方
  • 本番環境のGitLabを安全にアップグレードしたい方

アップグレードは、単に新しいパッケージをインストールしてコマンドを実行するだけではありません。事前の緻密な計画、入念な準備、そしてリスク管理が成功の鍵となります。失敗を恐れず、しかし油断せず、本記事で解説する手順とベストプラクティスに従って、安全かつスムーズなGitLabアップグレードを実現しましょう。

1. アップグレード前の準備フェーズ：成功は計画にあり

GitLabアップグレードの成否は、その準備段階でほぼ決まると言っても過言ではありません。このフェーズを怠ると、予期せぬ問題が発生した際に、迅速かつ適切に対応できなくなり、失敗のリスクが跳ね上がります。ここでは、アップグレード前に実施すべき重要な準備作業について、詳細に解説します。

1.1. 計画フェーズ：ロードマップの策定

1.1.1. 現在のGitLabバージョンの確認

まず、現在稼働しているGitLabの正確なバージョンを確認します。これは、アップグレードパスを決定する上で非常に重要です。

  • GitLabのWeb UIのフッターまたはヘルプメニューから確認できます。
  • サーバー上で gitlab-rake gitlab:env:info コマンドを実行することでも詳細な情報を取得できます。
  • /opt/gitlab/version-manifest ファイルを見る方法もあります（Omnibusの場合）。

バージョン情報（例: 16.7.2-ee.0）を控えておきましょう。EEはEnterprise Edition、CEはCommunity Editionを示します。

1.1.2. 目標バージョンの決定とアップグレードパスの確認

どのバージョンにアップグレードするかを決定します。

  • 推奨: 可能な限り、GitLabが推奨するLatest Releaseや、長期サポート版（LTS: Long Term Support）の最新マイナーバージョンを目指すのが安全です。LTSバージョンはセキュリティアップデートのみが提供され、機能変更が少ないため安定しています。
  • ジャンプアップ制限: GitLabには、メジャーバージョンや特定のバージョン間で「ジャンプアップ」できない制限があります。例えば、13.xから15.xに直接アップグレードできないなど、必ず中間バージョンを経由する必要があります。GitLabの公式ドキュメントにある「Upgrade path」を確認し、現在のバージョンから目標バージョンまでの正確なアップグレードパスを特定します。
    • 公式ドキュメント: https://docs.gitlab.com/ee/update/ の「Upgrade path」または「Version specific upgrading instructions」セクションを参照してください。
    • 例: 13.12 -> 14.9 -> 14.10 -> 15.0 -> 15.11 -> 16.0 -> … のように、複数のステップが必要になる場合があります。各ステップ間のアップグレードは、基本的には一つ前のメジャー/マイナーバージョンの最新版を経由するのが安全です（例: 13.12 -> 14.0 ではなく 13.12 -> 13.latest -> 14.0 のように）。ただし、多くの場合は最新のマイナーバージョンへの直接アップグレードが可能です（例: 14.0 -> 14.10 は可能）。重要なのは、公式ドキュメントで示されている必須の中間バージョンをスキップしないことです。

1.1.3. ダウンタイムの検討と関係者への通知

アップグレードには、多かれ少なかれサービス停止（ダウンタイム）が必要です。

  • アップグレードにかかる時間を概算します。これには、パッケージインストール、設定反映 (gitlab-ctl reconfigure)、データベースマイグレーション、キャッシュクリア、サービスの再起動、テストなどが含まれます。特にデータベースマイグレーションは、データ量が多いほど時間がかかります。
  • ジャンプアップが必要な場合は、各ステップでのダウンタイムの合計時間を考慮します。
  • 許容されるダウンタイムウィンドウを関係者（開発者、運用チーム、プロジェクトマネージャーなど）と調整します。
  • ダウンタイムの開始、終了予定時刻、および緊急連絡先などを事前に広く通知します。事前の通知は、予期せぬトラブル発生時の混乱を最小限に抑えます。

1.1.4. 必要なリソースの見積もりと確保

新しいGitLabバージョンは、より多くのシステムリソース（CPU、メモリ、ディスク容量）を要求する場合があります。

  • 目標バージョンのシステム要件を確認します。公式ドキュメントの「System requirements」セクションを参照してください。
  • 現在のリソース使用状況と比較し、増強が必要かどうか判断します。特に、データベースマイグレーション中に一時的に高いCPU/メモリ負荷がかかることがあります。
  • ディスク容量は、新しいパッケージのダウンロード、解凍、インストール、およびデータベースマイグレーション中に一時ファイルが増えるため、十分な空き容量が必要です。通常、インストール済みのGitLabの総容量の数倍程度の空き容量があると安心です。
  • クラウド環境の場合は、インスタンスタイプやディスクサイズの見直しを検討します。オンプレミスの場合は、ハードウェア増強の計画を立てます。

1.1.5. 利用中の機能や設定の棚卸し

現在利用しているGitLabの機能、外部サービス連携、カスタム設定などを洗い出します。

  • Omnibus Packageを使用している場合、/etc/gitlab/gitlab.rb ファイルに記載されている設定項目を確認します。デフォルトから変更している箇所をリストアップします。
  • SSL証明書、LDAP/SAML認証連携、SMTP設定、CI/CD Runners、Container Registry、Mattermost連携、監視ツール連携（Prometheusなど）、外部データベース利用など、デフォルト以外の設定や連携を全てリストアップします。
  • これらの設定が、目標バージョンで非推奨になっていないか、あるいは変更が必要ないか、リリースノートや公式ドキュメントで確認します。

1.1.6. カスタム設定や変更点の特定

/etc/gitlab/gitlab.rb 以外のファイルや、GitLabが管理するディレクトリ（/opt/gitlab 以下など）に対して、手動で変更を加えている場合は、それらを全て特定し、記録しておきます。例えば、Nginxの設定ファイルを直接編集している、特定のスクリプトを配置している、などです。これらの変更は、アップグレードによって上書きされる可能性があるため、事前のバックアップと、アップグレード後の再適用または再設定が必要になる場合があります。

1.2. 環境の準備：安全なテスト環境の確保

1.2.1. 本番環境と同等なステージング環境の構築

最も重要かつ強く推奨される準備作業です。本番環境とできる限り同じ構成、同じデータ量を持つステージング環境を構築します。

  • OSのバージョン、GitLabのバージョン、GitLabの構成（Omnibus/Source）、使用している外部サービス（データベース、オブジェクトストレージなど）、システムリソース（CPU, メモリ, ディスク）を本番環境と一致させます。
  • 本番環境から最新のバックアップを取得し、ステージング環境にリストアします。これにより、本番環境とほぼ同じ状態でアップグレードの予行演習を行うことができます。
  • ステージング環境は、本番環境から分離されており、テスト中に本番環境に影響を与えないようにします。

なぜステージング環境が必要なのか？

  • リスクの特定: アップグレード手順中の潜在的な問題（設定エラー、依存関係の問題、予期せぬエラーなど）を本番環境に影響を与えることなく発見できます。
  • 手順の検証: アップグレード手順そのもの（コマンドの実行順序、タイミングなど）が正しいか、漏れがないかを確認できます。
  • 時間見積もりの精度向上: バックアップからのリストア時間、アップグレード処理時間、データベースマイグレーション時間など、実際の作業にかかる時間を正確に見積もることができます。
  • トラブルシューティングの予行練習: 問題が発生した場合の切り分け方法や、リカバリ手順（ロールバック含む）を練習できます。
  • 機能テストの実施: アップグレード後のGitLabが期待通りに動作するか、主要な機能（リポジトリ操作、CI/CD、Web UIなど）が正常かを確認できます。

ステージング環境での予行演習を最低でも1回、できれば複数回実施し、アップグレード手順を洗練させ、発生した問題を全て解決しておくことが、失敗しないアップグレードの最も効果的な方法です。

1.2.2. テスト環境の準備（任意）

ステージング環境の他に、小規模なテスト環境を用意することも有効です。

  • データ量: 本番データ全てをリストアするのが難しい場合でも、一部のプロジェクトやユーザーデータを含む環境でテストできます。
  • 目的: 特定の機能（CI/CD、レジストリなど）や、特定のアップグレードパス（ジャンプアップの各ステップ）のみを重点的にテストするのに適しています。
  • 構築の容易さ: Dockerや仮想マシンで比較的簡単に構築できます。

1.3. バックアップフェーズ：唯一の救済策

バックアップは、アップグレード失敗時の最後の砦です。万が一の事態に備え、最新かつ検証済みのバックアップを取得しておくことは絶対条件です。

1.3.1. なぜバックアップが重要なのか？

アップグレードプロセス中に予期せぬエラー（データベースマイグレーションの失敗、ディスク障害、設定ミスなど）が発生し、GitLabが起動不能になったり、データが破損したりする可能性があります。このような状況から回復できる唯一の手段が、事前のバックアップからのリストアです。

1.3.2. バックアップ対象

GitLabのデータは複数の場所に分散しています。以下の要素を全てバックアップする必要があります。

  • GitLabデータ: リポジトリ、Wiki、プロジェクト・グループ情報、Issue、マージリクエスト、ユーザー情報、CI/CDジョブログ、LFSオブジェクトなど。これらは通常、データベースとファイルシステムに保存されます。
  • 設定ファイル: /etc/gitlab/gitlab.rb および /etc/gitlab/gitlab-secrets.json。gitlab-secrets.json にはCI/CDなどの暗号化キーが含まれており、リストア時に必須です。その他のカスタム設定ファイルも忘れずに。
  • Container Registryデータ: 使用している場合、通常は /var/opt/gitlab/gitlab-rails/shared/registry またはオブジェクトストレージに保存されます。
  • Gitalyデータ: Gitリポジトリの実体が保存されているディレクトリ (/var/opt/gitlab/git-data など)。
  • その他: CI/CDアーティファクト (/var/opt/gitlab/gitlab-rails/shared/artifacts など)、LFSオブジェクト (/var/opt/gitlab/gitlab-rails/shared/lfs-objects など)

1.3.3. バックアップ方法（Omnibus Package）

Omnibus Packageでは、gitlab-backup create コマンドが推奨されるバックアップ方法です。このコマンドは、データベース、リポジトリ、アップロードファイル、ビルドトレース、LFSオブジェクトなどを一括でバックアップします。

  • コマンド例:
    bash
    sudo gitlab-backup create
  • 保存先: デフォルトでは、/var/opt/gitlab/backups/ ディレクトリに [TIMESTAMP]_gitlab_backup.tar という形式のファイルが作成されます。このディレクトリはGitLabが管理しているため、このバックアップファイルを別の安全な場所（リモートストレージ、別のサーバーなど）にコピーしておくことが非常に重要です。
  • 除外設定: 必要に応じて、特定のデータをバックアップ対象から除外できます（例: CI/CDアーティファクトなど）。詳細は公式ドキュメントを参照してください。
  • バックアップの取得タイミング: アップグレード直前に、最新のバックアップを取得します。ダウンタイム開始直後に行うのが理想的です。

1.3.4. 手動バックアップが必要なケース

gitlab-backup create コマンドでバックアップされないデータや設定は、手動でバックアップする必要があります。

  • /etc/gitlab/ ディレクトリ全体（gitlab.rb, gitlab-secrets.json, SSL証明書など）。
    bash
    sudo cp -R /etc/gitlab/ /path/to/safe/location/gitlab_config_backup/
  • Container Registryがファイルシステムに保存されている場合（デフォルト）。
  • /opt/gitlab/ 以下に手動で変更を加えたファイル。
  • ログファイル（アップグレード前に過去のログをアーカイブしておくと、問題発生時の比較に役立ちます）。
  • 外部データベースを使用している場合は、そのデータベースのバックアップも別途取得します。PostgreSQLの場合は pg_dump などを利用します。

1.3.5. バックアップの検証：リストアテストの実施

バックアップファイルが正常に取得できているか、そして実際にリストア可能かを検証することは、バックアップを取得することと同等かそれ以上に重要です。バックアップファイルが存在しても、破損していたり、リストア手順が間違っていたりすると、いざという時に役に立ちません。

  • 検証環境: 前述のステージング環境（または別のクリーンなテスト環境）を利用します。
  • 手順:
    1. クリーンなOSに、バックアップを取得した時点と同じバージョンのGitLab Omnibus Packageをインストールします（設定は最小限で構いません）。
    2. GitLabを一度起動し、初期設定を行います。
    3. GitLabを停止します。
    4. バックアップファイル（.tar ファイル）を /var/opt/gitlab/backups/ ディレクトリに配置します（GitLabユーザーが読み取れる権限が必要です）。
    5. 設定ファイル (/etc/gitlab/gitlab.rb, gitlab-secrets.json) をリストアします。
    6. sudo gitlab-ctl reconfigure を実行します。
    7. sudo gitlab-backup restore BACKUP=[TIMESTAMP] コマンドでデータをリストアします。[TIMESTAMP] はバックアップファイル名から拡張子を除いた部分です。
    8. リストア完了後、GitLabを起動し、Web UIにアクセスできるか、プロジェクトデータが復旧しているかなどを確認します。
  • 重要: リストアテストは、少なくとも一度は実施し、その手順をドキュメント化しておきます。

1.3.6. バックアップ媒体の確保と管理

取得したバックアップファイルは、アップグレード対象のサーバーとは別の場所に安全に保管します。

  • リモートストレージ（S3互換ストレージ、NFSマウントなど）
  • 別のサーバーへのSCP/RSync
  • 専用のバックアップサーバー
  • オフラインメディア（磁気テープなど）

保管場所は、十分な容量があり、セキュリティが確保されている必要があります。また、バックアップファイルの世代管理や定期的な取得スケジュールの見直しも考慮しておきましょう。

1.4. ドキュメントと情報の収集

最新かつ正確な情報を手に入れることは、アップグレードを成功させる上で不可欠です。

1.4.1. 公式アップグレードドキュメントの入手と熟読

GitLabの公式ドキュメントは、アップグレード手順の唯一の信頼できる情報源です。

  • GitLabのバージョンごとに、特定のアップグレード手順が記述されています。特に、ジャンプアップが必要な場合は、中間バージョンごとのドキュメントを全て確認します。
  • 必須の確認事項:
    • アップグレードパス
    • バージョン固有の変更点（非推奨設定、廃止機能、デフォルト値の変更など）
    • 特別なマイグレーション手順やコマンドの実行が必要か
    • 既知の問題や回避策
    • リソース要件の変更
  • ドキュメントはPDFなどでダウンロードしておくと、オフライン環境でも参照できます。

1.4.2. リリースノート、変更履歴、非推奨機能の確認

アップグレード先のバージョンのリリースノートを詳細に確認します。

  • 破壊的な変更 (Breaking Changes): 既存の設定や運用に影響を与える可能性のある変更がないか、特に注意して確認します。
  • 非推奨機能 (Deprecations): 将来的に廃止される機能や設定がないか確認し、必要であれば代替手段への移行計画を立てます。
  • パフォーマンスに関する変更: データベースや特定の機能に関するパフォーマンス改善/劣化の情報。
  • 既知のバグ (Known Issues): アップグレード先のバージョンで報告されている既知のバグや、その影響範囲、回避策を確認します。GitLabのIssue Tracker（https://gitlab.com/gitlab-org/gitlab/issues）も参照します。

1.4.3. 利用中の外部サービスとの互換性確認

GitLabが連携している外部サービス（Jenkins, Jira, Slack, Kubernetesなど）や、サードパーティ製のGitLab連携ツールなどが、アップグレード後のGitLabバージョンと互換性があるかを確認します。外部サービスのドキュメントやサポート情報を参照します。

これらの準備作業を丁寧に行うことで、アップグレード中の予期せぬ事態を減らし、問題発生時にも落ち着いて対処できるようになります。時間はかかりますが、ダウンタイムやデータ損失のリスクを考えれば、投資する価値は十分にあります。

2. アップグレード手順の実行フェーズ：本番への適用

準備フェーズが完了したら、いよいよ実際のアップグレード手順を実行します。ここでは、ステージング環境での予行演習から本番環境での実行、そしてアップグレード後の確認までを詳細に解説します。

2.1. ステージング環境での予行演習

準備フェーズで構築したステージング環境で、本番環境と全く同じ手順でアップグレードを実行します。これは、本番での失敗を防ぐための最も重要なステップです。

2.1.1. 予行演習の実施

  1. 環境の準備: ステージング環境が本番環境の最新状態のバックアップからリストアされていることを確認します。
  2. アップグレード手順の実行: 準備フェーズで策定したアップグレードパスに従い、以下の手順を実行します。ジャンプアップが必要な場合は、全ての中間ステップを含めて実行します。
    • GitLabの停止: 全てのGitLab関連サービスを停止します。
      bash
      sudo gitlab-ctl stop
      （SidekiqやCronなどのバックグラウンドジョブも停止していることを確認します。）
    • 既存パッケージのバックアップ（任意だが推奨）: 現在インストールされているGitLabパッケージそのものや、重要な設定ファイルを再度バックアップします。
      bash
      # 設定ファイル
      sudo cp -a /etc/gitlab /path/to/safe/location/staging_gitlab_config_pre_upgrade_backup/
      # gitlab.rb だけでも良い
      sudo cp /etc/gitlab/gitlab.rb /path/to/safe/location/staging_gitlab.rb.pre_upgrade
      # secrets ファイル
      sudo cp /etc/gitlab/gitlab-secrets.json /path/to/safe/location/staging_gitlab-secrets.json.pre_upgrade
    • 新しいバージョンのパッケージインストール:
      • 対象バージョンのOmnibus Packageをダウンロードします。パッケージはGitLabのパッケージリポジトリから取得できます。
      • RHEL/CentOS系 (YUM/DNF):
        bash
        # リポジトリ設定済みの場合
        sudo yum install gitlab-ee-[version] # または gitlab-ce-[version]
        # またはダウンロードしたrpmファイルをインストール
        sudo rpm -Uvh gitlab-ee-[version].rpm
      • Debian/Ubuntu系 (APT):
        bash
        # リポジトリ設定済みの場合
        sudo apt update
        sudo apt install gitlab-ee=[version] # または gitlab-ce=[version]
        # またはダウンロードしたdebファイルをインストール
        sudo dpkg -i gitlab-ee_[version].deb
      • [version] の部分には、目標とするGitLabのバージョン（例: 16.7.2-ee.0）を指定します。リポジトリからインストールする場合は、パッケージマネージャーにバージョンを指定しないと最新版（必ずしも目標バージョンではない）がインストールされる可能性があるため注意が必要です。バージョンを指定してインストールできない場合は、ダウンロードしたパッケージファイルを使用します。
    • gitlab-ctl reconfigure の実行: このコマンドが、設定ファイルの読み込み、各サービスのコンフィグ生成、パーミッション設定、そしてデータベースマイグレーションを含む多くの重要な処理を実行します。
      bash
      sudo gitlab-ctl reconfigure
      このコマンドの出力、特にデータベースマイグレーションに関するメッセージを注意深く監視します。エラーが発生した場合は、メッセージを記録します。
    • データベースマイグレーションの監視: gitlab-ctl reconfigure 中に実行されるデータベースマイグレーションは、データ量によっては非常に時間がかかります。進行状況を示すメッセージが出力されるので、これを監視します。エラーが発生していないか確認します。詳細なログは /var/log/gitlab/gitlab-rails/migrations.log などに出力されます。
    • gitlab-ctl restart の実行: 全てのGitLabサービスを再起動します。
      bash
      sudo gitlab-ctl restart
    • サービスの起動確認: 全てのサービスが正常に起動したか確認します。
      bash
      sudo gitlab-ctl status
      出力が全て run となっていることを確認します。一部のサービスが down の場合は、ログを確認して原因を特定します。
    • ログファイルの確認: /var/log/gitlab/ 以下の各サービスのログファイル（gitlab-rails/production.log, sidekiq/current, postgresql/current, nginx/current など）にエラーメッセージが出力されていないか確認します。
  3. アップグレード後の確認とテスト: 次のセクションで詳述するテストを実行します。
  4. 問題の記録と手順の修正: 予行演習中に発生した全ての問題（エラーメッセージ、予期せぬ挙動、テストの失敗など）を記録し、その解決策や回避策を明確にします。アップグレード手順書を修正し、問題への対処方法を含めます。必要であれば、再度予行演習を実施して修正した手順を検証します。
  5. 時間計測: アップグレード開始から全てのテストが完了するまでの時間を計測し、本番でのダウンタイム見積もりに反映させます。

2.1.2. 予行演習の繰り返し

特に重要なアップグレード（メジャーバージョンアップやジャンプアップ）の場合、予行演習を複数回行うことを検討します。例えば、一度予行演習を行って手順を修正した後、再度本番環境の最新バックアップを取得してリストアし、修正した手順で再度実行するなどです。これにより、手順の正確性と安定性を高めることができます。

2.2. 本番環境での実行（計画されたダウンタイム中）

予行演習で手順が確立され、問題なくアップグレードが完了することを確認できたら、いよいよ本番環境でのアップグレードを実行します。

2.2.1. 開始前の最終確認

  • バックアップの確認: アップグレード直前に取得した最新のバックアップファイル（データと設定ファイル）が、別の安全な場所にコピーされていることを再確認します。
  • ディスク容量、メモリ、CPU負荷の確認: システムリソースに十分な余裕があるか、再度確認します。
  • 全ユーザーへのダウンタイム通知: 事前に通知したダウンタイムの開始を再度告知します。
  • GitLabへのアクセス制限: ユーザーがアップグレード中にアクセスしないように、Web UIの表示をメンテナンスモードにする、あるいはNginxなどのフロントエンドでメンテナンスページを表示するなど、アクセス制限を行います。
    • Omnibusの場合、/etc/gitlab/gitlab.rb でメンテナンスモードを有効にできます。
      ruby
      # gitlab.rb
      gitlab_rails['enable_maintenance_mode'] = true
      変更を反映するには sudo gitlab-ctl reconfigure が必要です。アクセス制限としては、ファイアウォールでGitLabへのアクセスを一時的にブロックする方が確実な場合もあります。
  • CI/CD Runnerの停止: アップグレード中にCI/CDジョブが実行されないように、登録されている全てのRunnerを停止または無効化します。

2.2.2. 実際のアップグレード手順

ステージング環境で検証済みの手順書に従って、正確に作業を進めます。

  1. システムの停止:
    bash
    sudo gitlab-ctl stop
    全てのプロセスが停止するまで待ちます。
  2. 既存パッケージのバックアップ: /etc/gitlab ディレクトリ全体、特に gitlab.rb と gitlab-secrets.json をバックアップします。
    bash
    sudo cp -a /etc/gitlab /path/to/safe/location/production_gitlab_config_pre_upgrade_backup/
    これらのファイルは、万が一ロールバックが必要になった際に、元の状態に戻すために不可欠です。
  3. 新しいバージョンのパッケージインストール: ステージング環境で成功したのと同じ方法で、ターゲットバージョンのOmnibus Packageをインストールします。
    • 重要な注意: gitlab-ctl reconfigure の実行前に、古いバージョンの /etc/gitlab/gitlab.rb を新しい環境にコピーします。新しいパッケージにはデフォルトの gitlab.rb が含まれていますが、これを使用すると既存の設定が失われます。必ず、アップグレード対象のサーバーの既存の /etc/gitlab/gitlab.rb を使用します。
      “`bash

    例: 新しいパッケージがインストールされた後、古い設定ファイルを上書きコピー

    sudo cp /path/to/production_gitlab_config_pre_upgrade_backup/gitlab.rb /etc/gitlab/gitlab.rb

    gitlab-secrets.json も同様にコピー

    sudo cp /path/to/production_gitlab_config_pre_upgrade_backup/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json
    ``
    GitLabのバージョンによっては、    gitlab.rbのフォーマットが変更されている場合があります。gitlab-ctl reconfigureが実行されると、古いgitlab.rbが自動的に新しいフォーマットに変換されることがありますが、**予期せぬ変更がないか、アップグレード後にgitlab.rb` を確認することは重要です。**

  4. gitlab-ctl reconfigure の実行と監視:
    bash
    sudo gitlab-ctl reconfigure
    このコマンドの出力をリアルタイムで監視します。特にデータベースマイグレーションの進行状況とエラーメッセージに注意します。問題が発生した場合は、すぐに原因究明と対処に移ります。予行演習で発生した問題とその解決策をまとめたドキュメントを参考にします。
  5. データベースマイグレーションの実行と監視: gitlab-ctl reconfigure の一部として自動的に実行されます。データ量が多いほど時間がかかります。進捗が表示されない場合でも、バックグラウンドで実行されていることがあります。長時間変化がない場合は、ログファイル (/var/log/gitlab/gitlab-rails/migrations.log) を確認します。
  6. gitlab-ctl restart の実行:
    bash
    sudo gitlab-ctl restart
  7. gitlab-ctl status でサービスの起動確認:
    bash
    sudo gitlab-ctl status
    全てのサービスが run 状態になっているか確認します。起動しないサービスがある場合は、そのサービスのログを確認します。
  8. ログファイルの監視: /var/log/gitlab/ 以下の各サービスのログファイルを再度確認し、エラーメッセージや異常な出力がないか確認します。

2.2.3. 段階的なアップグレード（ジャンプアップの場合）

ジャンプアップが必要な場合は、上記の手順を中間バージョンごとに繰り返します。

  • 13.12 -> 14.9 -> 14.10 -> 15.0 -> … のように、一つずつバージョンを上げていきます。
  • 各バージョンへのアップグレードステップ（パッケージインストール -> reconfigure -> restart -> 確認）が完了するたびに、そのバージョンでGitLabが正常に起動し、基本的な機能が動作することを確認します。
  • 特にメジャーバージョンを跨ぐアップグレード（例: 14.10 -> 15.0）では、破壊的な変更が含まれている可能性が高いので、各ステップ後の確認はより慎重に行います。
  • 各ステップで gitlab-ctl reconfigure を実行する際に、データベースマイグレーションが実行されます。マイグレーションは常に前方互換性を持つわけではないため、一度新しいバージョンにマイグレーションされたデータベースを古いバージョンで読み込むことはできません（これがロールバックを難しくする要因です）。各ステップで確実にマイグレーションが成功していることを確認します。

2.3. アップグレード後の確認とテスト

アップグレードが物理的に完了し、サービスが起動したら、GitLabが正常に機能していることを入念にテストします。これは、予行演習で実施したテスト項目に沿って行います。

  1. GitLabへのログインテスト: 管理者アカウントと、代表的な一般ユーザーアカウントでログインできるか確認します。
  2. Web UIの確認: インターフェースが正常に表示されるか、主要なページ（ダッシュボード、プロジェクト一覧、設定画面など）にアクセスできるか確認します。
  3. 基本的な機能テスト:
    • 新しいプロジェクト/グループを作成できるか
    • 既存のプロジェクトにアクセスできるか
    • リポジトリのクローン、コミット、プッシュ、プルができるか
    • マージリクエストを作成、レビュー、マージできるか
    • Issueを作成、コメントできるか
  4. 特定の利用頻度の高い機能、カスタマイズ機能のテスト:
    • CI/CDパイプラインの実行テスト（簡単なパイプラインをトリガーして成功することを確認）
    • Container Registryの利用テスト（イメージのプッシュ/プル）
    • 外部認証（LDAP/SAMLなど）でのログインテスト
    • Webhookが正常に送信されるか
    • カスタマイズした設定（例: Nginx設定、ストレージ設定）が正しく反映されているか
    • 外部サービス連携（Jira連携、Slack通知など）が機能するか
  5. システムパフォーマンスの監視: アップグレード直後から、サーバーのCPU、メモリ、ディスクI/O、データベース負荷などを監視ツールで確認します。通常時と比較して異常な負荷がかかっていないか確認します。
  6. ログファイルのエラー確認: /var/log/gitlab/ 以下のログファイルを再度詳細に確認し、アップグレード後に発生しているエラーメッセージがないか確認します。
  7. gitlab-rake gitlab:check の実行: このコマンドは、GitLabのインストール状態、パーミッション、設定などを包括的にチェックしてくれます。
    bash
    sudo gitlab-rake gitlab:check SANITIZE=true
    SANITIZE=true オプションを付けると、出力からセンシティブな情報がマスクされます。出力された問題点や警告は、必要に応じて対処します。

全てのテストが成功し、システム監視でも異常が見られないことを確認できたら、アップグレードは一旦成功と判断できます。

3. アップグレード後の作業フェーズ：後処理と最適化

アップグレードが完了し、基本的な動作確認が終わった後も、いくつか重要な作業が残っています。これらの作業は、システムの安定性維持と、新しいバージョンの利活用に役立ちます。

3.1. パフォーマンスチューニング（必要であれば）

新しいバージョンにアップグレードしたことで、特定の処理のパフォーマンスが変化する可能性があります。

  • アップグレード後のシステム監視で高い負荷が観測されたサービス（例: PostgreSQL, Sidekiq）があれば、そのサービスの設定を見直し、チューニングを検討します。
  • データベースのVACUUMやANALYZEを適切に実行する（PostgreSQLの場合）。
  • GitLabのパフォーマンス設定 (gitlab.rb の sidekiq, puma/unicorn, redis, postgresql などの設定）を見直す。公式ドキュメントのパフォーマンスに関するセクションを参照してください。

3.2. 新しい機能の有効化と設定（オプション）

アップグレードしたバージョンで追加された新機能の中から、組織にとって有用なものがあれば、その設定と有効化を検討します。リリースノートや公式ドキュメントを参照し、機能を理解した上で慎重に導入します。

3.3. 関係者へのアップグレード完了通知

アップグレード作業が完了し、サービスが正常に復旧したことを、事前に通知した関係者全員に伝えます。また、今回のアップグレードで導入された主な変更点や新機能についても簡単に周知すると良いでしょう。

3.4. 古いバックアップの整理

アップグレードに成功し、システムが安定稼働していることを確認できたら、アップグレード前に取得した古いバージョンのバックアップデータや、アップグレード中に作成した一時ファイルなどを整理します。ただし、万が一に備え、アップグレード直前のバックアップは一定期間保持しておくことを推奨します。

3.5. アップグレード手順と発生した問題の記録

今回のアップグレード作業で実施した詳細な手順、発生した問題、その原因と解決策、かかった時間などを記録しておきます。この記録は、将来のアップグレード計画やトラブルシューティングの際に非常に役立ちます。特にステージング環境での予行演習の結果と本番での結果を比較検討し、手順書を更新しておくと良いでしょう。

4. 失敗した場合の対応フェーズ：トラブルシューティングとロールバック

残念ながら、どんなに入念な準備をしても、アップグレード中に予期せぬ問題が発生する可能性はゼロではありません。ここでは、問題発生時の切り分け方法、一般的なトラブルシューティング、そして最終手段としてのロールバック手順について解説します。

4.1. 問題発生時の切り分け

アップグレード中にエラーが発生したり、アップグレード後にGitLabが正常に起動しない・動作しない場合は、落ち着いて原因の切り分けを行います。

  • ログファイルの確認: まずは /var/log/gitlab/ 以下の各サービスのログファイルを確認します。
    • gitlab-rails/production.log: GitLab Railsアプリケーションのログ。ユーザー操作やWeb UI関連のエラーが出力されます。
    • sidekiq/current: バックグラウンドジョブ（CI/CD、メール送信など）関連のログ。
    • postgresql/current または mysql/current: データベース関連のログ。
    • nginx/current: Nginx（Webサーバー）関連のログ。
    • gitaly/current: Git操作関連のログ。
    • reconfigure/current: gitlab-ctl reconfigure 実行時のログ。最も重要なログの一つです。
    • migrations.log (または db/migrate 配下): データベースマイグレーションの詳細ログ。
  • gitlab-ctl status: どのサービスが起動していないか確認します。
  • gitlab-ctl tail [service_name]: 特定サービスのリアルタイムログを確認できます。
  • gitlab-ctl check-config: GitLabの設定ファイルに構文エラーがないかチェックします。
  • gitlab-rake gitlab:check: GitLabの各コンポーネントが正常に設定され、動作しているか包括的にチェックします。エラーが出力された場合は、そのメッセージに従って対処します。sudo gitlab-rake gitlab:check SANITIZE=true で実行します。

エラーメッセージの内容を正確に把握し、どのコンポーネント（Rails, Sidekiq, DB, Nginx, Gitalyなど）で問題が発生しているかを特定することが、トラブルシューティングの第一歩です。

4.2. 一般的なトラブルシューティング

特定された問題に応じて、以下の一般的な対処法を試みます。

  • gitlab-ctl reconfigure の再実行: 設定ファイルに誤りがあった場合など、gitlab-ctl reconfigure を再度実行することで問題が解決することがあります。ただし、データベースマイグレーションは冪等ではない処理が含まれるため、マイグレーションが原因の場合は単純な再実行では解決しない場合があります。
  • データベース接続の確認: GitLab Railsや他のサービスがデータベースに接続できているか確認します。データベースサーバー自体が起動しているか、GitLabサーバーからDBサーバーへのネットワーク経路に問題ないか、認証情報は正しいかなどを確認します。
  • パーミッションの問題: ファイルやディレクトリのパーミッションが正しく設定されているか確認します。gitlab-ctl reconfigure が多くのパーミッションを修正しますが、手動で変更した箇所などが問題になることがあります。
  • ディスク容量不足: 一時ファイルやログファイルでディスク容量が枯渇していないか確認します。
  • メモリ不足: サーバーのメモリ使用率が高すぎないか確認します。特にデータベースマイグレーション中は大量のメモリを消費することがあります。
  • 外部サービスとの連携問題: LDAP, SMTP, オブジェクトストレージなどの外部サービスとの連携に問題がないか確認します。認証情報の変更、ネットワーク障害、外部サービス側の問題などが考えられます。
  • 設定ファイル (gitlab.rb) の見直し: アップグレード後に gitlab.rb の一部設定がデフォルトに戻っていないか、あるいは新しいバージョンで非推奨・廃止された設定を使っていないか確認します。特に、アップグレード前に手動で変更した設定項目が正しく引き継がれているか確認します。

公式ドキュメントのトラブルシューティングセクションや、GitLabのIssue Tracker、フォーラムなども参考に、発生したエラーメッセージで検索してみると、同様の問題に遭遇した他のユーザーの解決策が見つかることがあります。

4.3. ロールバック手順

上記のトラブルシューティングで問題が解決しない場合や、アップグレード作業に計画以上の時間がかかりダウンタイムウィンドウを超過しそうな場合は、アップグレード前の状態へのロールバックを検討します。

4.3.1. なぜロールバックが必要になるか？

アップグレードに失敗し、システムが正常に機能しない状態が続くことは、開発・運用プロセスを完全に停止させる可能性があります。このような場合、一時的にでもサービスを復旧させるために、アップグレード前の安定した状態に戻す（ロールバックする）ことが必要になります。

4.3.2. ロールバックの限界（データベースマイグレーションの不可逆性）

重要な注意点: GitLabのアップグレードに含まれるデータベースマイグレーションは、原則として不可逆です。つまり、一度新しいバージョン向けにマイグレーションされたデータベースは、古いバージョンのGitLabでは読み込めません。したがって、アップグレード中のデータベースマイグレーションが一部でも実行されてしまった後にロールバックする場合、単に古いGitLabパッケージに戻すだけでは不十分であり、必ずアップグレード前に取得したデータベースバックアップからリストアする必要があります。 これが、アップグレード前のバックアップ取得とリストアテストが決定的に重要な理由です。

4.3.3. バックアップからのリストア手順

ロールバックは、実質的には「アップグレード失敗バージョンを破棄し、アップグレード前バージョンのクリーンな環境に、アップグレード前のバックアップをリストアする」という手順になります。

  1. GitLabサービスの停止:
    bash
    sudo gitlab-ctl stop
  2. 現在のGitLabパッケージの削除（任意だが推奨）: アップグレード失敗バージョンのGitLabパッケージを削除します。これにより、システムをクリーンな状態に戻すことができます。
    • RHEL/CentOS系: sudo yum remove gitlab-ee または sudo rpm -e gitlab-ee
    • Debian/Ubuntu系: sudo apt remove gitlab-ee または sudo dpkg -r gitlab-ee
    • 設定ファイル（/etc/gitlab）やデータディレクトリ（/var/opt/gitlab）は通常削除されません。
  3. データディレクトリの退避または削除: 現在のデータディレクトリ（/var/opt/gitlab など）を、バックアップからのリストアに備えて退避または削除します。ただし、手動で追加したファイルなど、バックアップに含まれていない重要なデータがないか十分に確認してから実行してください。 安全のため、完全に削除するのではなく、別の場所に移動させるのが無難です。
    bash
    sudo mv /var/opt/gitlab /var/opt/gitlab_failed_upgrade_backup
  4. アップグレード前と同じバージョンのGitLabパッケージのインストール: ロールバック先のバージョン（アップグレード開始前と同じバージョン）のOmnibus Packageをインストールします。
    • パッケージマネージャーでバージョンを指定してインストールするか、ダウンロードしたパッケージファイルを使用します。
  5. 設定ファイルのリストア: アップグレード前にバックアップしておいた /etc/gitlab/ ディレクトリ（特に gitlab.rb と gitlab-secrets.json）を元の場所に戻します。
    bash
    sudo cp -a /path/to/safe/location/production_gitlab_config_pre_upgrade_backup/ /etc/gitlab/
  6. gitlab-ctl reconfigure の実行: 設定ファイルを再読み込みさせます。
    bash
    sudo gitlab-ctl reconfigure
    この時点ではデータベースは空または古いままですが、ファイルシステム上の必要なディレクトリなどが再作成されます。
  7. バックアップファイルの配置: アップグレード直前に取得し、安全な場所に保管しておいたバックアップファイル（.tar ファイル）を /var/opt/gitlab/backups/ ディレクトリにコピーします。GitLabユーザーが読み取れるように権限を調整します。
  8. バックアップからのリストア:
    bash
    sudo gitlab-backup restore BACKUP=[TIMESTAMP] --force
    [TIMESTAMP] はバックアップファイル名から拡張子を除いた部分です。 --force オプションは、既存のデータディレクトリが存在する場合に上書きを強制するために必要になることがあります（ただし、事前にデータディレクトリを退避または削除していれば不要かもしれません。公式ドキュメントで正確な手順を確認してください）。リストア処理は、データ量によっては非常に時間がかかります。
  9. リストア後の確認: リストア処理が正常に完了したか、出力メッセージを確認します。
  10. GitLabの起動:
    bash
    sudo gitlab-ctl start
  11. サービスの起動確認: sudo gitlab-ctl status で全てのサービスが起動しているか確認します。
  12. 基本的な機能テスト: Web UIへのアクセス、ログイン、プロジェクトへのアクセスなど、最低限の機能が復旧しているか確認します。

ロールバックは、データ損失のリスクを伴う可能性があるため、最後の手段として行うべきです。ロールバック後は、なぜアップグレードに失敗したのか原因を徹底的に究明し、問題を解決してから再度アップグレード計画を立て直します。

4.3.4. ダウンタイムの延長と通知

ロールバックは、アップグレードにかかる時間以上の時間を要することがほとんどです。計画していたダウンタイムウィンドウを大幅に超過する可能性が高いため、速やかに状況を関係者に通知し、サービス復旧の目処を伝えます。

5. よくある問題と対策

GitLabアップグレードでしばしば遭遇する一般的な問題と、その対策をまとめます。

  • データベースマイグレーションの失敗/遅延:
    • 原因: データ量が多い、データベースサーバーのリソース不足、過去の不整合データ、ネットワーク問題など。
    • 対策: データベースサーバーのリソース増強、アップグレード前に gitlab-rake gitlab:check でDBの不整合をチェック、PostgreSQLの場合はVACUUMやANALYZEを事前に実行。ログ (/var/log/gitlab/gitlab-rails/migrations.log) を確認し、エラーメッセージに従って対処。必要であれば、GitLabサポートに問い合わせ。
  • gitlab-ctl reconfigure のエラー:
    • 原因: gitlab.rb の設定ミス、ファイルパーミッションの問題、依存サービスの起動失敗、ディスク容量不足など。
    • 対策: gitlab.rb の構文チェック (gitlab-ctl check-config)、ログ (/var/log/gitlab/reconfigure/current) を確認し、エラーメッセージに従って対処。ファイルパーミッションは gitlab-ctl reconfigure で修正されることが多いが、手動で変更した箇所がないか確認。
  • サービスが起動しない:
    • 原因: 上記 reconfigure の失敗、設定ミス、リソース不足、依存サービスの未起動など。
    • 対策: gitlab-ctl status でどのサービスがダウンしているか特定。そのサービスのログ (/var/log/gitlab/[service_name]/current) を確認。gitlab-ctl tail [service_name] でリアルタイムログを確認。gitlab-ctl reconfigure を再実行してみる。
  • パフォーマンスの著しい低下:
    • 原因: 新しいバージョンのリソース要件増加、非効率なデータベースクエリ、設定の変更、システムリソース不足など。
    • 対策: システムリソース（CPU, メモリ, IO）の使用率を監視。データベースサーバーの負荷を確認。gitlab.rb のパフォーマンス関連設定（Puma/Unicornワーカー数、Sidekiqコンカレンシーなど）を見直し。必要であれば、データベースのVACUUM/ANALYZEを実行。
  • 特定機能の不具合:
    • 原因: 設定ミス、外部サービス連携の問題、キャッシュの問題、バージョン固有のバグなど。
    • 対策: その機能に関連する設定項目 (gitlab.rb) を確認。関連サービスのログを確認。外部サービスとの連携設定を見直し。gitlab-ctl cache-clear を実行してみる（慎重に）。既知のバグでないか公式 Issue Tracker を確認。
  • GitLab Shell / Gitaly の問題:
    • 原因: Gitリポジトリへのアクセス権限問題、Gitalyサービス自体の問題、設定ミス。
    • 対策: gitlab-rake gitlab:check で関連項目をチェック。Gitalyサービスのログを確認。gitlab.rb の gitaly 設定を確認。リポジトリディレクトリのパーミッションを確認。
  • カスタム設定の上書き:
    • 原因: gitlab-ctl reconfigure が実行される際に、デフォルトのテンプレートで設定ファイルが上書きされる。
    • 対策: アップグレード前に /etc/gitlab ディレクトリ全体をバックアップしておく。アップグレード後に gitlab.rb を確認し、意図しない変更がないか確認。手動で変更した他の設定ファイルがないか確認し、必要であれば再適用または再設定する。

これらの問題の多くは、事前のステージング環境でのテストで発見し、対処法を確立しておくことが可能です。

6. まとめ

GitLabのアップグレードは、その規模と複雑さゆえに慎重なアプローチが求められる作業です。しかし、本記事で解説したように、徹底した準備と計画、段階的な実行、そして万全なバックアップとリカバリ体制を整えることで、「失敗しない」アップグレードを実現することは可能です。

失敗しないための最重要ポイント:

  1. 計画: 現在の状況把握、アップグレードパスの決定、ダウンタイム計画、リソース見積もり、利用機能の棚卸しを丁寧に行う。
  2. テスト: 本番環境と同等なステージング環境を構築し、本番と同様の手順で最低1回、できれば複数回アップグレードの予行演習を行う。 予行演習で発見した問題は全て記録し、手順を洗練させる。
  3. バックアップ: アップグレード直前に、データと設定ファイルの完全なバックアップを取得する。 そして、そのバックアップが実際にリストア可能かをステージング環境などで検証する。バックアップファイルは、アップグレード対象サーバーとは別の場所に保管する。
  4. ドキュメント: 公式ドキュメント、リリースノート、アップグレードパスを熟読し、バージョン固有の注意点や変更点を把握する。独自のアップグレード手順書を作成し、予行演習結果を反映して更新する。
  5. 監視と確認: アップグレード中およびアップグレード後は、システムログ、サービスの状態、システムリソースを注意深く監視し、問題がないか確認する。アップグレード後の機能テストを確実に行う。

アップグレードは一度行えば終わりではなく、GitLabを継続的に利用していく上で定期的に実施する必要があります。これらの手順とベストプラクティスを組織の標準手順として確立することで、将来のアップグレードもよりスムーズかつ安全に行えるようになります。

本記事が、皆さんのGitLabアップグレードを成功に導く一助となれば幸いです。安全なDevOps環境を維持するためにも、定期的なアップグレードを計画的に実施していきましょう。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール