GitLabの復元

GitLabはインストール全体をリストアするためのコマンドラインインターフェイスを提供しており、ニーズに合わせて柔軟に対応できます。

リストアの前提条件のセクションには重要な情報が含まれています。本番環境で実行しようとする前に、少なくとも一度は完全なリストアプロセスを読み、テストするようにしてください。

リストアの前提条件

リストア先のGitLabインスタンスがすでに動作していること

リストアを実行する前に、GitLabのインストールが動作している必要があります。リストアアクションを実行するシステムユーザー (git) は通常、データのインポートに必要な SQL データベースを作成したり削除したりすることができないからです (gitlabhq_production)。既存のデータはすべて消去されるか（(SQL) ）、別のディレクトリに移動されます（リポジトリやアップロードなど）。SQLデータのリストアは、PostgreSQL拡張が所有するビューをスキップします。

リストア先のGitLabインスタンスは全く同じバージョンでなければなりません。

バックアップをリストアできるのは、作成したGitLabと全く同じバージョンとタイプ（CEまたはEE）のみです。例えば、CE 15.1.4。

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

GitLabシークレットはリストアする必要があります。

バックアップをリストアするには、GitLabシークレットもリストアする必要があります。これらには、データベースの暗号化キー、CI/CD変数、二要素認証に使用される変数が含まれます。キーがないと、二要素認証を有効にしているユーザーがアクセスできなくなったり、GitLab Runnerがログインできなくなるなど、複数のイシューが発生します。

復元します：

特定のGitLab設定はバックアップされた元の環境と一致している必要があります。

また、以前の/etc/gitlab/gitlab.rb (Linux パッケージインストールの場合) や/home/git/gitlab/config/gitlab.yml (セルフコンパイルインストールの場合) や TLS キー、証明書 (/etc/gitlab/ssl,/etc/gitlab/trusted-certs)、SSH ホストキーもリストアしておきましょう。

特定の設定はPostgreSQLのデータと結合しています。例えば

  • 内部環境に3つのリポジトリストレージ（例えば、default 、my-storage-1 、my-storage-2）がある場合、ターゲット環境にも少なくともこれらのストレージ名が設定で定義されていなければなりません。
  • ターゲット環境がオブジェクトストレージを使用している場合でも、ローカルストレージを使用している環境からバックアップをリストアすると、ローカルストレージにリストアされます。オブジェクトストレージへのマイグレーションは、リストアの前または後に行う必要があります。

マウントポイントであるディレクトリのリストア

マウントポイントになっているディレクトリにリストアする場合は、リストアする前にこれらのディレクトリが空であることを確認する必要があります。そうしないと、GitLabは新しいデータをリストアする前にこれらのディレクトリを移動しようとしてエラーになります。

NFSマウントの設定についてはこちらをご覧ください。

Linuxパッケージインストールのリストア

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

  • バックアップを作成したのとまったく同じバージョンとタイプ（CE/EE）のGitLabをインストールしていること。
  • sudo gitlab-ctl reconfigure を少なくとも一度実行していること。
  • 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 。

次に、リストアしたいバックアップのタイムスタンプを指定してバックアップをリストアします：

# This command will overwrite the contents of your GitLab database!
# NOTE: "_gitlab_backup.tar" is omitted from the name
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

バックアップのtarファイルとインストールされているGitLabのバージョンに不一致がある場合、restoreコマンドはエラーメッセージを出して中断します。正しいGitLabのバージョンをインストールしてから、もう一度試してください。

caution
インストールがPgBouncerを使用している場合、パフォーマンス上の理由やPatroniクラスターで使用する場合、restoreコマンドは追加のパラメータを必要とします。

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

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

GitLab 13.1以降では、特に/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

DockerイメージとGitLab Helmチャートのインストールの復元

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

どちらのインストールタイプでも、バックアップのtarボールがバックアップの場所（デフォルトの場所は/var/opt/gitlab/backups ）になければなりません。

Helmチャートインストールのリストア

GitLab HelmチャートはGitLab Helmチャートインストールのリストアで説明されているプロセスを使います。

Dockerイメージインストールのリストア

Docker Swarmを使用している場合、Pumaがシャットダウンしているため、コンテナのヘルスチェックが失敗し、リストア処理中にコンテナが再起動することがあります。この問題を回避するには、ヘルスチェック機構を一時的に無効にします。

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

    healthcheck:
  disable: true

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

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

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

リストアタスクはホストから実行することができます：

# 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

セルフコンパイルインストールのリストア

まず、バックアップ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 ユーザーが所有する必要があります。これで、バックアップ手順を開始できます：

# 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]

次に、前述のように、必要に応じて/home/git/gitlab/.secret をリストアします。

GitLabを再起動します：

sudo service gitlab restart

バックアップから1つまたは少数のプロジェクトやグループのみをリストアする場合

GitLabインスタンスをリストアするためのRakeタスクは単一のプロジェクトやグループのリストアをサポートしていませんが、別の一時的なGitLabインスタンスにバックアップをリストアし、そこからプロジェクトやグループをエクスポートすることで回避することができます：

  1. リストア元のインスタンスと同じバージョンの新しいGitLabインスタンスをインストールします。
  2. この新しいインスタンスにバックアップをリストアし、プロジェクトや グループをエクスポートします。エクスポートされるものとされないものの詳細については、エクスポート機能のドキュメントをご覧ください。
  3. エクスポートが完了したら、古いインスタンスに移動し、インポートします。
  4. 必要なプロジェクトやグループのインポートが完了したら、新しい一時的なGitLabインスタンスを削除してください。

個々のプロジェクトやグループを直接リストアする機能については、イシュー#17517 で検討中です。

リポジトリの増分バックアップのリストア

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

リストアオプション

GitLabが提供するバックアップからのリストアのためのコマンドラインツールは、より多くのオプションを受け入れることができます。

バックアップが複数ある場合にリストアするバックアップを指定します。

デフォルトでは、バックアップ・ファイルはタイムスタンプで始まる命名スキームを使用します。複数のバックアップが存在する場合は、環境変数BACKUP=timestamp_of_backup を設定して、リストアする*_gitlab_backup.tar ファイルを指定する必要があります。

リストア中のプロンプトの無効化

バックアップからのリストア中、リストア スクリプトには確認のプロンプトが表示されます：

  • 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 環境変数もこれらのプロンプトを無効にします。

リストア時のタスクの除外

GitLab 14.10で導入されました。

SKIP という環境変数を追加することで、リストア時に特定のタスクを除外することができます：

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

特定のタスクを除外します：

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

     sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads

  • セルフコンパイルによるインストール：

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

特定のリポジトリ・ストレージの復元

GitLab 15.0 で導入されました。

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

使用例：

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

     sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2

  • セルフコンパイルによるインストール：

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

特定のリポジトリの復元

GitLab 15.1で導入されました。

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=timestamp_of_backup 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=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

未復刻バックアップの復元

未復元バックアップ（SKIP=tar で作成）が見つかり、BACKUP=<timestamp>でバックアップが選択されていない場合、未復元バックアップが使用されます。

使用例：

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

     sudo gitlab-backup restore

  • セルフコンパイルによるインストール：

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

トラブルシューティング

以下は、遭遇する可能性のある問題とその解決策です。

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実行します。gitlab リストアが開始されると、これもユーザーとして実行さ gitlabれますが、アクセス権を持たないオブジェクトを変更しようとします。これらのオブジェクトはデータベースのバックアップやリストアには影響しませんが、警告メッセージを表示します。

詳細については