GitLabを復元する

GitLabの復元操作により、バックアップからデータを復元してシステムの継続性を維持し、データ損失から回復できます。この操作では、以下のデータを復元します:

• データベースレコードと設定
• Gitリポジトリ、コンテナレジストリイメージ、アップロードされたコンテンツ
• パッケージレジストリのデータとCI/CDアーティファクト
• アカウントとグループの設定
• プロジェクトとグループのWiki
• プロジェクトレベルの安全なファイル
• 外部マージリクエストの差分

復元プロセスでは、バックアップと同じバージョンの既存のGitLabインストールが必要です。本番環境で使用する前に、前提要件に従い、復元プロセス全体をテストしてください。

復元の前提要件

復元先のGitLabインスタンスがすでに動作している必要がある

復元を実行するには、正常に動作しているGitLabインストールが必要です。これは、復元操作を実行するシステムユーザー（git）には、通常、データをインポートするために必要なSQLデータベース（gitlabhq_production）の作成や削除を行う権限がないためです。既存のデータはすべて消去される（SQL）か、別のディレクトリに移動されます（リポジトリやアップロードファイルなど）。SQLデータの復元では、PostgreSQL拡張機能が所有しているビューはスキップされます。

復元先のGitLabインスタンスがまったく同じバージョンである必要がある

バックアップは、作成時とまったく同じバージョンおよびタイプ（CEまたはEE）のGitLabにのみ復元できます。たとえば、CE 15.1.4などです。

バックアップのバージョンが現在のインストールと異なる場合は、バックアップを復元する前に、GitLabインストールをダウングレードまたはアップグレードする必要があります。

GitLabシークレットを復元する必要がある

バックアップを復元するには、GitLabシークレットも復元する必要があります。新しいGitLabインスタンスに移行する場合は、旧サーバーからGitLabのシークレットファイルをコピーしなくてはなりません。これには、データベース暗号化キー、CI/CD変数、および2要素認証に使用される変数などが含まれます。キーがないと、複数の問題が発生します。たとえば、2要素認証が有効になっているユーザーがアクセスできなくなったり、GitLab Runnerがサインインできなくなったりします。

インストール方法に基づいて、以下を復元する:

/etc/gitlab/gitlab-secrets.json

/srv/gitlab/config/gitlab-secrets.json

/home/git/gitlab/.secret

こちらも参照してください:

• CI/CD変数
• 2要素認証
• シークレットのトラブルシューティングに関するイシュー

特定のGitLabの設定がバックアップ元の環境と一致している必要がある

復元する際は、以前の/etc/gitlab/gitlab.rb（Linuxパッケージインストールの場合）または/home/git/gitlab/config/gitlab.yml（セルフコンパイルインストールの場合）と、TLSまたはSSHキーと証明書を個別に復元することがあります。

特定の設定は、PostgreSQLのデータに結び付いています。次に例を示します:

• 元の環境に3つのリポジトリのストレージ（例: default、my-storage-1、my-storage-2）がある場合、復元先の環境にも、それらのストレージ名が設定で定義されている必要があります。
• 元の環境がローカルストレージを使用している場合、バックアップを復元するとローカルストレージに復元されます。たとえ復元先の環境がオブジェクトストレージを使用している場合でも同様です。オブジェクトストレージへの移行は、復元前または復元後に行う必要があります。

詳細については、バックアップに含まれないデータを参照してください。

マウントポイントであるディレクトリを復元する

マウントポイントであるディレクトリに復元する場合は、復元を試みる前に、これらのディレクトリが空であることを確認する必要があります。確認しない場合、GitLabは新しいデータを復元する前にこれらのディレクトリを移動しようとするため、エラーが発生します。

NFSマウントの設定の詳細を参照してください。

LinuxパッケージインストールのGitLabを復元する

この手順では、以下を前提としています:

• バックアップを作成した際とまったく同じバージョンおよびタイプ（CE/EE）のGitLabをインストールしている。
• sudo gitlab-ctl reconfigureを少なくとも1回実行している。
• GitLabが起動している。起動していない場合は、sudo gitlab-ctl startを実行して起動します。

まず、バックアップのtarファイルが、gitlab.rbの設定項目gitlab_rails['backup_path']で指定されたバックアップディレクトリにあることを確認します。デフォルトは/var/opt/gitlab/backupsです。バックアップファイルは、gitユーザーが所有している必要があります。

sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar

データベースに接続しているプロセスを停止します。その他のGitLabのプロセスは実行したままにします:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# Verify
sudo gitlab-ctl status

次に、復元の前提要件の手順を完了し、元のインストールからGitLabのシークレットファイルをコピーした後、gitlab-ctl reconfigureを実行したことを確認します。

続いて、復元するバックアップのIDを指定してバックアップを復元します:

# NOTE: "_gitlab_backup.tar" is omitted from the name
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

バックアップのtarファイルと現在インストールされているGitLabのバージョンが一致しない場合、復元コマンドは中止され、次のエラーメッセージが表示されます:

GitLab version mismatch:
  Your current GitLab version (16.5.0-ee) differs from the GitLab version in the backup!
  Please switch to the following version and try again:
  version: 16.4.3-ee

正しいGitLabバージョンをインストールしてから、再度試してください。

PostgreSQLノードでreconfigureを実行します:

sudo gitlab-ctl reconfigure

次に、GitLabを起動して確認します:

sudo gitlab-ctl start
sudo gitlab-rake gitlab:check SANITIZE=true

特に/etc/gitlab/gitlab-secrets.jsonが復元された場合、または別のサーバーが復元先である場合は、データベースの暗号化キーを復号化できることを確認します。

sudo gitlab-rake gitlab:doctor:secrets

さらに確実性を高めるため、復元されたファイルの整合性チェックを実行できます:

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

復元が完了したら、データベース統計を生成することが推奨されます。これにより、データベースのパフォーマンスが向上し、UIの不整合を防ぐことができます:

1. データベースコンソールに入ります。

2. 次を実行します:

   SET STATEMENT_TIMEOUT=0 ; ANALYZE VERBOSE;

このコマンドを復元コマンドに統合することについて、現在も議論が続いています。詳細については、イシュー276184を参照してください。

復元後の検証ガイド:

• GitLab設定
• データベースの値が復号化できることを確認する
• アップロードされたファイルの整合性チェック:

DockerイメージインストールおよびGitLab HelmチャートインストールのGitLabを復元する

DockerイメージまたはKubernetesクラスター上のGitLab Helmチャートを使用してGitLabをインストールしている場合、復元タスクは復元先ディレクトリが空であることを前提としています。しかし、DockerおよびKubernetesのボリュームマウントでは、Linuxオペレーティングシステムに見られるlost+foundディレクトリなど、一部のシステムレベルのディレクトリがボリュームルートに作成される場合があります。これらのディレクトリは通常rootが所有しており、復元のRakeタスクはgitユーザーとして実行されるため、アクセス権限エラーが発生する可能性があります。GitLabインストールを復元するには、復元先ディレクトリが空であることを確認する必要があります。

これらのインストールタイプの場合、バックアップのtarballがバックアップの配置場所で使用可能である必要があります（デフォルトの場所は/var/opt/gitlab/backupsです）。

HelmチャートインストールのGitLabを復元する

GitLab Helmチャートでは、GitLab Helmチャートインストールを復元するに記載された手順に従います。

DockerイメージインストールのGitLabを復元する

Docker Swarmを使用している場合、復元プロセス中にPumaがシャットダウンされるため、コンテナのヘルスチェックに失敗し、コンテナが再起動する可能性があります。この問題を回避するには、ヘルスチェックメカニズムを一時的に無効にします。

1. docker-compose.ymlを編集します:

   healthcheck:
     disable: true

2. スタックをデプロイします:

   docker stack deploy --compose-file docker-compose.yml mystack

詳細については、イシュー6846を参照してください。

ホストから復元タスクを実行できます:

# Stop the processes that are connected to the database
docker exec -it <name of container> gitlab-ctl stop puma
docker exec -it <name of container> gitlab-ctl stop sidekiq

# Verify that the processes are all down before continuing
docker exec -it <name of container> gitlab-ctl status

# Run the restore. NOTE: "_gitlab_backup.tar" is omitted from the name
docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

# Restart the GitLab container
docker restart <name of container>

# Check GitLab
docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true

自己コンパイルによるインストールのGitLabを復元する

1. まず、バックアップのtarファイルが、gitlab.yml設定で指定されたバックアップディレクトリにあることを確認します:

   ## Backup settings
   backup:
     path: "tmp/backups"   # Relative paths are relative to Rails.root (default: tmp/backups/)

   デフォルトは/home/git/gitlab/tmp/backupsで、gitユーザーが所有している必要があります。

2. バックアップ手順を開始します:

   # Stop processes that are connected to the database
   sudo service gitlab stop
   
   sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production

   出力例:

   Unpacking backup... [DONE]
   Restoring database tables:
   -- create_table("events", {:force=>true})
     -> 0.2231s
   [...]
   - Loading fixture events...[DONE]
   - Loading fixture issues...[DONE]
   - Loading fixture keys...[SKIPPING]
   - Loading fixture merge_requests...[DONE]
   - Loading fixture milestones...[DONE]
   - Loading fixture namespaces...[DONE]
   - Loading fixture notes...[DONE]
   - Loading fixture projects...[DONE]
   - Loading fixture protected_branches...[SKIPPING]
   - Loading fixture schema_migrations...[DONE]
   - Loading fixture services...[SKIPPING]
   - Loading fixture snippets...[SKIPPING]
   - Loading fixture taggings...[SKIPPING]
   - Loading fixture tags...[SKIPPING]
   - Loading fixture users...[DONE]
   - Loading fixture users_projects...[DONE]
   - Loading fixture web_hooks...[SKIPPING]
   - Loading fixture wikis...[SKIPPING]
   Restoring repositories:
   - Restoring repository abcd... [DONE]
   - Object pool 1 ...
   Deleting tmp directories...[DONE]

3. 必要に応じて/home/git/gitlab/.secretを復元します。

4. GitLabを再起動します:

   sudo service gitlab restart

バックアップから1つまたは少数のプロジェクトまたはグループのみを復元する

GitLabインスタンスの復元に使用するRakeタスクは、単一のプロジェクトまたはグループの復元をサポートしていません。しかし回避策として、バックアップを別の一時的なGitLabインスタンスに復元し、そこからプロジェクトまたはグループをエクスポートすることが可能です:

1. 復元対象のバックアップされたインスタンスと同じバージョンのGitLabを新たにインストールします。
2. この新しいインスタンスにバックアップを復元し、そこからプロジェクトまたはグループをエクスポートします。エクスポートされる項目とされない項目の詳細については、エクスポート機能のドキュメントを参照してください。
3. エクスポートが完了したら、元のインスタンスに移動してインポートします。
4. 目的のプロジェクトまたはグループのインポートが完了したら、新しい一時的なGitLabインスタンスは削除してもかまいません。

個々のプロジェクトやグループを直接復元できるようにする機能リクエストについては、イシュー17517で議論されています。

増分リポジトリバックアップを復元する

各バックアップアーカイブには、増分リポジトリバックアップ手順で作成されたものを含め、完全な自己完結型バックアップが含まれています。増分リポジトリバックアップを復元するには、他の通常のバックアップアーカイブを復元する場合と同じ手順を使用します。

復元オプション

バックアップからの復元に使用するGitLabのコマンドラインツールには、他にも多くのオプションを指定できます。

複数のバックアップがある場合に復元するバックアップを指定する

バックアップファイルは、バックアップIDで始まる命名スキームを使用します。バックアップが複数存在する場合は、環境変数BACKUP=<backup-id>を設定して、復元する<backup-id>_gitlab_backup.tarファイルを指定する必要があります。

復元中にプロンプトを無効にする

バックアップからの復元中、復元スクリプトは次のタイミングで確認のプロンプトを表示します:

• Write to authorized_keys（authorized_keysへの書き込み）設定が有効になっている場合は、復元スクリプトがauthorized_keysファイルを削除して再構築する前。
• データベースの復元時、復元スクリプトが既存のテーブルをすべて削除する前。
• データベースの復元後、スキーマの復元でエラーが発生し、続行するとさらに問題が発生する可能性がある場合。

これらのプロンプトを無効にするには、GITLAB_ASSUME_YES環境変数を1に設定します。

• Linuxパッケージインストール:

  sudo GITLAB_ASSUME_YES=1 gitlab-backup restore

• 自己コンパイルによるインストール:

  sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production

force=yes環境変数もこれらのプロンプトを無効にします。

復元時にタスクを除外する

環境変数SKIPを追加して、復元時に特定のタスクを除外できます。この変数の値には、次のオプションのカンマ区切りリストを指定します:

• db（データベース）
• uploads（添付ファイル）
• builds（CIジョブの出力ログ）
• artifacts（CIジョブのアーティファクト）
• lfs（LFSオブジェクト）
• terraform_state（Terraformステート）
• registry（コンテナレジストリイメージ）
• pages（Pagesコンテンツ）
• repositories（Gitリポジトリデータ）
• packages（パッケージ）

特定のタスクを除外するには、次の手順に従います:

• Linuxパッケージインストール:

  sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads

• 自己コンパイルによるインストール:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production

特定のリポジトリのストレージを復元する

複数のリポジトリのストレージを使用している場合、REPOSITORIES_STORAGESオプションを使用することで、特定のリポジトリのストレージにあるリポジトリを個別に復元できます。このオプションは、カンマ区切りのストレージ名のリストを受け入れます。

次に例を示します:

• Linuxパッケージインストール:

  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2

• 自己コンパイルによるインストール:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2

特定のリポジトリを復元する

REPOSITORIES_PATHSおよびSKIP_REPOSITORIES_PATHSオプションを使用して、特定のリポジトリを復元できます。これらのオプションには、プロジェクトまたはグループのパスをカンマ区切りリストで指定します。グループのパスを指定した場合、使用するオプションに応じて、そのグループおよび下位グループ内のすべてのプロジェクトに含まれるすべてのリポジトリが、バックアップ対象に含まれるかスキップされます。グループおよびプロジェクトは、指定したバックアップ内または復元先インスタンス上に存在する必要があります。

たとえば、グループA（group-a）内のすべてのプロジェクトのすべてのリポジトリと、グループB（group-b/project-c）内のプロジェクトCのリポジトリを復元し、グループA（group-a/project-d）内のプロジェクトDをスキップする場合、次のように指定します:

• Linuxパッケージインストール:

  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

• 自己コンパイルによるインストール:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

展開済みバックアップを復元する

展開済みバックアップ（SKIP=tarを使用して作成）が見つかり、BACKUP=<backup-id>で特定のバックアップが指定されていない場合は、その展開済みバックアップが使用されます。

次に例を示します:

• Linuxパッケージインストール:

  sudo gitlab-backup restore

• 自己コンパイルによるインストール:

  sudo -u git -H bundle exec rake gitlab:backup:restore

サーバー側のリポジトリバックアップを使用した復元

サーバー側のバックアップを収集すると、復元プロセスは、サーバー側のリポジトリのバックアップを作成するに示されているサーバー側の復元メカニズムをデフォルトで使用します。各リポジトリをホストするGitalyノードが、必要なバックアップデータをオブジェクトストレージから直接プルできるように、バックアップの復元を設定できます。

1. Gitalyでサーバー側のバックアップ先を設定します。
2. サーバー側のバックアップ復元プロセスを開始し、復元するバックアップのIDを指定します:

sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=11493107454_2018_04_25_10.6.4-ce

kubectl exec <Toolbox pod name> -it -- backup-utility --restore -t <backup_ID> --repositories-server-side

トラブルシューティング

起こり得る問題と考えられる解決策を次に示します。

Linuxパッケージインストール環境でデータベースバックアップの復元時に出力される警告

バックアップの復元手順を使用している場合、次のような警告メッセージが表示されることがあります:

ERROR: must be owner of extension pg_trgm
ERROR: must be owner of extension btree_gist
ERROR: must be owner of extension plpgsql
WARNING:  no privileges could be revoked for "public" (two occurrences)
WARNING:  no privileges were granted for "public" (two occurrences)

このような警告メッセージが表示されても、バックアップは正常に復元されていることに注意してください。

Rakeタスクはgitlabユーザーとして実行されますが、このユーザーにはデータベースに対するスーパーユーザーアクセス権がありません。復元が開始される際も同様にgitlabユーザーとして実行されますが、アクセス権のないオブジェクトを変更しようとします。これらのオブジェクトは、データベースのバックアップや復元には影響しませんが、警告メッセージが表示されます。

詳細については、以下を参照してください:

• PostgreSQLイシュートラッカー:

  • スーパーユーザーではない。
  • オーナーが異なる。

• スタックオーバーフロー: 発生するエラー。

Gitサーバーフックが原因で復元が失敗する

バックアップから復元する際に次の条件に当てはまる場合、エラーが発生することがあります:

• Gitサーバーフック（custom_hook）が、GitLabバージョン15.10以前の方法で設定されている
• 使用しているGitLabバージョンが15.11以降である
• GitLabの管理下にないディレクトリへのシンボリックリンクを作成している

次のようなエラーが出力されます:

{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}

この問題を解決するには、GitLabバージョン15.11以降向けにGitサーバーフックを更新し、新しいバックアップを作成してください。

fapolicydを使用している場合に、復元は成功するがリポジトリが空と表示される

セキュリティを強化するためにfapolicydを使用すると、GitLabは復元に成功したと報告していても、リポジトリが空と表示されることがあります。その他のトラブルシューティングのヘルプについては、Gitalyのトラブルシューティングのドキュメントを参照してください。