GitLabをバックアップする

GitLabのバックアップは、データを保護し、ディザスターリカバリーに役立ちます。

最適なバックアップ戦略は、GitLabのデプロイ設定、データ量、ストレージの場所によって異なります。これらの要因によって、使用するバックアップ方法、バックアップの保存場所、バックアップスケジュールの構成方法が決まります。

大規模なGitLabインスタンスの場合、代替バックアップ戦略には次のようなものがあります:

• 増分バックアップ。
• 特定のリポジトリのバックアップ。
• 複数のストレージの場所にわたるバックアップ。

バックアップに含まれるデータ

GitLabは、インスタンス全体をバックアップするためのコマンドラインインターフェースを提供しています。デフォルトでは、バックアップを行うと、単一の圧縮されたtarファイルとしてアーカイブが作成されます。このファイルには、次のものが含まれます:

• データベースのデータと設定
• アカウントとグループの設定
• CI/CDアーティファクトとジョブログ
• GitリポジトリとLFSオブジェクト
• 外部マージリクエストの差分
• パッケージレジストリデータとコンテナレジストリイメージ
• プロジェクトとグループのWiki
• プロジェクトレベルの添付ファイルとアップロード
• セキュアファイル
• GitLab Pagesコンテンツ
• Terraformステート
• スニペット

バックアップに含まれないデータ

• Mattermostのデータ
• Redis（およびそれに依存するSidekiqジョブ）
• Linuxパッケージ（Omnibus）/Docker/自己コンパイルによるインストール環境のオブジェクトストレージ
• グローバルサーバーフック
• ファイルフック
• GitLabの設定ファイル（/etc/gitlab）
• TLSおよびSSH関連のキーと証明書
• その他のシステムファイル

簡単なバックアップ手順

おおまかなガイドラインとして、100 GB未満のデータで1kリファレンスアーキテクチャを使用している場合は、次の手順に従います:

1. バックアップコマンドを実行します。
2. 該当する場合は、オブジェクトストレージをバックアップします。
3. システム設定ファイルを手動でバックアップします。

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

• 1kリファレンスアーキテクチャ
• バックアップコマンドの詳細
• オブジェクトストレージの設定
• 設定ファイルガイド

バックアップをスケールする

GitLabのデータ量が増加するにつれて、バックアップコマンドの実行にかかる時間が長くなります。Gitリポジトリを同時にバックアップしたり、差分リポジトリをバックアップするなど、バックアップオプションを使用すると、実行時間を短縮できます。状況によっては、バックアップコマンド自体が現実的でなくなることがあります。24時間以上かかる場合があるためです。

GitLab 18.0以降、大量の参照（ブランチ、タグ）があるリポジトリのリポジトリバックアップのパフォーマンスが大幅に向上しました。この改善により、影響を受けるリポジトリのバックアップ時間を数時間から数分に短縮できます。この機能強化を利用するために設定を変更する必要はありません。

バックアップをスケールできるようにするために、アーキテクチャの変更が必要になることがあります。

さらに詳しく:

• 増分リポジトリバックアップ。
• Gitリポジトリを同時にバックアップ。
• 大規模なリファレンスアーキテクチャをバックアップおよび復元する。
• 代替バックアップ戦略。
• GitLabリポジトリのバックアップ時間の短縮に関するブログ記事。

バックアップする必要のあるデータ

以下のデータをバックアップする必要があります。

PostgreSQLデータベース

GitLabの最も単純なケースでは、他のすべてのGitLabサービスと同じ仮想マシン（VM）上に1つのPostgreSQLサーバーがあり、そのサーバー上に1つのPostgreSQLデータベースが存在します。ただし、設定によっては、複数のPostgreSQLサーバーで複数のPostgreSQLデータベースを使用する場合もあります。

一般に、このデータは、イシューやマージリクエストのコンテンツ、コメント、権限、認証情報など、Webインターフェース内のほとんどのユーザー生成コンテンツの信頼できる唯一の情報源となります。

PostgreSQLは、HTMLレンダリングされたMarkdownなどのキャッシュデータや、デフォルトではマージリクエストの差分も保持します。ただし、マージリクエストの差分は、ファイルシステムまたはオブジェクトストレージにオフロードするように設定することもできます。

Gitaly Cluster (Praefect)は、PostgreSQLデータベースを信頼できる唯一の情報源として使用して、Gitalyノードを管理します。

一般的なPostgreSQLユーティリティであるpg_dumpは、PostgreSQLデータベースの復元に使用できるバックアップファイルを生成します。バックアップコマンドは、内部でこのユーティリティを使用しています。

残念ながら、データベースのサイズが大きくなるほど、pg_dumpの実行時間が長くなります。状況によっては、その所要時間が現実的ではなくなります（たとえば、数日かかるなど）。データベースが100 GBを超える場合、pg_dumpはもちろん、そのバックアップコマンドも実質的に使えない可能性があります。詳細については、代替バックアップ戦略を参照してください。

Gitリポジトリ

GitLabインスタンスには、1つ以上のリポジトリシャードを設定できます。各シャードは、ローカルに保存されたGitリポジトリへのアクセスと操作を可能にするGitalyインスタンスまたはGitaly Clusterです。Gitalyは、次のマシンで実行できます:

• 単一のディスクを使用しているマシン。
• 複数のディスクが（RAIDアレイなどの構成により）単一のマウントポイントとしてマウントされているマシン。
• LVMを使用しているマシン。

各プロジェクトには、最大で3種類のリポジトリを設定できます:

• ソースコードを保存するプロジェクトリポジトリ。
• Wikiコンテンツを保存するWikiリポジトリ。
• デザインアーティファクトをインデックス登録するデザインリポジトリ（実際のアセットはLFSに保存されます）。

これらのリポジトリはすべて同じシャード内に存在し、Wikiリポジトリとデザインリポジトリは同じベース名を共有し、それぞれ-wikiおよび-designというサフィックスが付きます。

パーソナルスニペットやプロジェクトスニペット、グループWikiコンテンツは、Gitリポジトリに保存されます。

プロジェクトのフォークは、プールリポジトリを使用して、稼働中のGitLabサイトで重複排除されます。

バックアップコマンドは、各リポジトリに対してGitバンドルを作成し、それらをすべてtar形式でアーカイブします。これにより、プールリポジトリデータがすべてのフォークに複製されます。当社のテストでは、100 GBのGitリポジトリをバックアップしてS3にアップロードするのに、2時間強かかりました。Gitデータが約400 GBに達する場合、バックアップコマンドを定期バックアップに使用するのは現実的ではないと考えられます。詳細については、代替バックアップ戦略を参照してください。

blob

GitLabは、イシューの添付ファイルやLFSオブジェクトなどのblob（またはファイル）を、次のいずれかに保存します:

• 特定の場所にあるファイルシステム。
• オブジェクトストレージソリューション。オブジェクトストレージソリューションには、次のものがあります:
  • Amazon S3やGoogle Cloud Storageなど、クラウドベースのもの。
  • ユーザー自身がホストするもの（MinIOなど）。
  • オブジェクトストレージ互換APIを提供するストレージアプライアンス。

オブジェクトストレージ

バックアップコマンドは、ファイルシステムに保存されていないblobをバックアップしません。オブジェクトストレージを使用している場合は、オブジェクトストレージプロバイダーでバックアップを有効にしてください。

プロバイダー固有のバックアップガイド:

• Amazon S3のバックアップ
• Google Cloud Storage Transfer Service
• Google Cloud Storageオブジェクトのバージョニング

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

• バックアップコマンドの詳細
• オブジェクトストレージの設定

コンテナレジストリ

GitLabコンテナレジストリストレージは、次のいずれかで設定できます:

• 特定の場所にあるファイルシステム。
• オブジェクトストレージソリューション。オブジェクトストレージソリューションには、次のものがあります:
  • Amazon S3やGoogle Cloud Storageなど、クラウドベースのもの。
  • ユーザー自身がホストするもの（MinIOなど）。
  • オブジェクトストレージ互換APIを提供するストレージアプライアンス。

レジストリデータがオブジェクトストレージに保存されている場合、バックアップコマンドはそれらのデータをバックアップしません。

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

• GitLabコンテナレジストリ
• オブジェクトストレージの設定

設定ファイルの保存

設定ディレクトリをバックアップする必要があります。少なくとも、次のファイルは必ずバックアップするようにしてください:

また、フルマシンを復元する必要がある場合に、中間者攻撃の警告を回避するため、TLSキーと証明書（/etc/gitlab/ssl、/etc/gitlab/trusted-certs）、SSHホストキーもバックアップすることをおすすめします。

万が一シークレットファイルを紛失した場合は、シークレットファイルを紛失した場合を参照してください。

その他のデータ

GitLabは、キャッシュストアとして、およびバックグラウンドジョブシステムSidekiqの永続データの保存先として、Redisを使用します。提供されているバックアップコマンドは、Redisデータをバックアップしません。つまり、バックアップコマンドを使用して一貫性のあるバックアップを作成するには、保留中または実行中のバックグラウンドジョブが存在してはいけません。

Elasticsearchは、高度な検索のためのオプションのデータベースです。これにより、ソースコードレベルと、イシュー、マージリクエスト、ディスカッションにおけるユーザー生成コンテンツの両方で、検索を改善できます。バックアップコマンドは、Elasticsearchのデータをバックアップしません。Elasticsearchのデータは、復元後にPostgreSQLデータから再生成できます。

手動バックアップオプション:

• Redisバックアップ手順
• Elasticsearchバックアップ手順

こちらも参照してください:バックアップコマンドの詳細。

要件

バックアップと復元を実行できるようにするには、rsyncがシステムにインストールされていることを確認してください。GitLabのインストール方法により、次のように条件が異なります:

• Linuxパッケージを使用した場合、rsyncはすでにインストールされています。
• 自己コンパイルを使用している場合は、rsyncがインストールされているかどうかを確認し、インストールされていない場合はインストールします。

バックアップコマンド

• バックアップコマンドは、Linuxパッケージ (Omnibus) / Docker / セルフコンパイルインストール環境では、オブジェクトストレージ内のアイテムをバックアップしません。
• バックアップコマンドでは、パフォーマンス上の理由、またはPatroniクラスターで使用する場合、設定でPgBouncerを使用するインストールの場合、追加のパラメータが必要です。
• バックアップは、作成時とまったく同じバージョンおよびタイプ（CE/EE）のGitLabにのみ復元できます。

重要な考慮事項:

• オブジェクトストレージの制限事項
• PgBouncerの設定要件

バックアップを作成するには:

sudo gitlab-backup create

docker exec -t <container name> gitlab-backup create

sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production

GitLabデプロイに複数のノードがある場合は、バックアップコマンドを実行するノードを1つ選択する必要があります。選択したノードが次の条件を満たしていることを確認してください:

• 永続的なノードであり、自動スケーリングの対象ではない。
• GitLab Railsアプリケーションがすでにインストールされている。PumaまたはSidekiqが実行されている場合は、Railsがインストールされています。
• バックアップファイルを作成できる十分なストレージとメモリがある。

出力例:

Dumping database tables:
- Dumping table events... [DONE]
- Dumping table issues... [DONE]
- Dumping table keys... [DONE]
- Dumping table merge_requests... [DONE]
- Dumping table milestones... [DONE]
- Dumping table namespaces... [DONE]
- Dumping table notes... [DONE]
- Dumping table projects... [DONE]
- Dumping table protected_branches... [DONE]
- Dumping table schema_migrations... [DONE]
- Dumping table services... [DONE]
- Dumping table snippets... [DONE]
- Dumping table taggings... [DONE]
- Dumping table tags... [DONE]
- Dumping table users... [DONE]
- Dumping table users_projects... [DONE]
- Dumping table web_hooks... [DONE]
- Dumping table wikis... [DONE]
Dumping repositories:
- Dumping repository abcd... [DONE]
Creating backup archive: <backup-id>_gitlab_backup.tar [DONE]
Deleting tmp directories...[DONE]
Deleting old backups... [SKIPPING]

バックアッププロセスの詳細については、バックアップアーカイブプロセスを参照してください。

バックアップオプション

インスタンスのバックアップ用にGitLabが提供するコマンドラインツールでは、さらに多くのオプションを利用できます。

バックアップ戦略オプション

デフォルトのバックアップ戦略では、基本的にLinuxコマンドのtarおよびgzipを使用し、各データの保存場所からバックアップ先へデータをストリーミングします。この方法はほとんどの場合に問題なく機能しますが、データが急速に変化している場合には問題が発生する可能性があります。

tarがデータを読み取っている最中にデータが変更されると、file changed as we read itというエラーが発生し、バックアッププロセスが失敗する原因となります。そのような場合には、copyというバックアップ戦略を使用できます。この戦略では、tarおよびgzipを呼び出す前に、データファイルを一時的な場所にコピーすることで、このエラーを回避します。

副作用として、このバックアッププロセスには追加で最大1倍のディスク容量が必要になります。プロセスは各段階で一時ファイルを可能な限りクリーンアップし、問題を悪化させないよう努めていますが、大規模なインストール環境では大きな変化となる可能性があります。

デフォルトのストリーミング戦略ではなくcopy戦略を使用するには、RakeタスクのコマンドでSTRATEGY=copyを指定します。次に例を示します:

sudo gitlab-backup create STRATEGY=copy

バックアップファイル名

バックアップファイルは、特定のデフォルトの命名規則に従って作成されます。ただし、BACKUP環境変数を設定することで、ファイル名の<backup-id>部分をオーバーライドできます。次に例を示します:

sudo gitlab-backup create BACKUP=dump

この場合、作成されるファイル名はdump_gitlab_backup.tarになります。これは、rsyncや増分バックアップを使用するシステム向けに便利です。転送速度を大幅に向上させることができます。

バックアップの圧縮

デフォルトでは、次のバックアップ時に、Gzipの高速圧縮を適用します:

• PostgreSQLデータベースのダンプ。
• blob（アップロード、ジョブアーティファクト、外部マージリクエストの差分など）。

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

• PostgreSQLデータベース
• blob

デフォルトのコマンドはgzip -c -1です。このコマンドは、COMPRESS_CMDでオーバーライドできます。同様に、解凍コマンドはDECOMPRESS_CMDでオーバーライドできます。

注意事項:

• 圧縮コマンドはパイプラインで使用するため、カスタムコマンドはstdoutに出力する必要があります。
• GitLabにパッケージ化されていないコマンドを指定する場合は、そのコマンドを自分でインストールする必要があります。
• この場合でも、生成されるファイル名の末尾は.gzになります。
• 復元時に使用されるデフォルトの解凍コマンドはgzip -cdです。したがって、gzip -cdで解凍できない形式に圧縮コマンドをオーバーライドした場合は、復元時にも解凍コマンドをオーバーライドする必要があります。
• 環境変数は、バックアップコマンドの後に記述しないでください。たとえば、gitlab-backup create COMPRESS_CMD="pigz -c --best"は、意図したとおりに動作しません。

デフォルトの圧縮: 高速のGzip

gitlab-backup create

低速のGzip

COMPRESS_CMD="gzip -c --best" gitlab-backup create

gzipを使用してバックアップを作成した場合は、復元時にオプションを指定する必要はありません:

gitlab-backup restore

圧縮なし

バックアップ先に自動圧縮機能が備わっている場合は、圧縮をスキップすることをおすすめします。

teeコマンドは、stdinをstdoutにパイプ処理します。

COMPRESS_CMD=tee gitlab-backup create

復元時のコマンドは次のとおりです:

DECOMPRESS_CMD=tee gitlab-backup restore

pigzを使用した並列圧縮

pigzを使用して4つの並列プロセスでバックアップを圧縮する例:

COMPRESS_CMD="pigz --compress --stdout --fast --processes=4" sudo gitlab-backup create

pigzはgzip形式で圧縮します。したがって、pigzで圧縮されたバックアップを解凍する際にpigzを使用する必要はありません。ただし、gzipよりもパフォーマンス上のメリットを得られる可能性があります。pigzを使用してバックアップを解凍する例:

DECOMPRESS_CMD="pigz --decompress --stdout" sudo gitlab-backup restore

zstdを使用した並列圧縮

zstdを使用して4つのスレッドでバックアップを圧縮する例:

COMPRESS_CMD="zstd --compress --stdout --fast --threads=4" sudo gitlab-backup create

zstdを使用してバックアップを解凍する例:

DECOMPRESS_CMD="zstd --decompress --stdout" sudo gitlab-backup restore

アーカイブが転送可能であることを確認する

生成されたアーカイブをrsyncで転送できるようにするには、GZIP_RSYNCABLE=yesオプションを設定します。これは、--rsyncableオプションをgzipに渡しますが、バックアップファイル名のオプションを設定する場合にのみ効果があります。

gzipの--rsyncableオプションは、すべてのディストリビューションで利用できるとは限りません。お使いのディストリビューションで利用できるかどうかを確認するには、gzip --helpを実行するか、manページを参照してください。

sudo gitlab-backup create BACKUP=dump GZIP_RSYNCABLE=yes

バックアップから特定のデータを除外する

インストールタイプにより、バックアップ作成時にスキップできるコンポーネントが若干異なります。

sudo gitlab-backup create SKIP=db,uploads

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

SKIP=は、次の目的にも使用されます:

• tarファイルの作成をスキップする（SKIP=tar）。
• リモートストレージへのバックアップのアップロードをスキップする（SKIP=remote）。

tarファイルの作成をスキップする

バックアップ作成の最終ステップは、すべての要素を含む.tarファイルの生成です。場合によっては、.tarファイルの作成が無駄になったり、直接的に悪影響が及んだりする可能性があります。そのため、SKIP環境変数にtarを追加することで、このステップをスキップできます。想定されるユースケースは次のとおりです:

• バックアップが他のバックアップソフトウェアに引き継がれる場合。
• 毎回バックアップを展開する必要をなくすことで、増分バックアップを高速化する場合（この場合、PREVIOUS_BACKUPおよびBACKUPは指定しないでください。指定してしまった場合、その指定されたバックアップはいったん展開されますが、最終的に.tarファイルは生成されません）。

SKIP変数にtarを追加すると、バックアップデータが保存されているファイルやディレクトリが、中間ファイル用のディレクトリに残されます。これらのファイルは、新しいバックアップを作成する際に上書きされるため、別の場所にコピーしておく必要があります。システム上にはバックアップを1つしか保持できないためです。

sudo gitlab-backup create SKIP=tar

sudo -u git -H bundle exec rake gitlab:backup:create SKIP=tar RAILS_ENV=production

サーバー側のリポジトリのバックアップを作成する

大規模なリポジトリのバックアップをバックアップアーカイブに保存するのではなく、各リポジトリをホストするGitalyノードがバックアップを作成し、オブジェクトストレージにストリーミングできるように設定することが可能です。これにより、バックアップの作成と復元に必要なネットワークリソースを削減できます。

1. Gitalyでサーバー側のバックアップ先を設定します。
2. リポジトリのサーバー側オプションを使用してバックアップを作成します。次の例を参照してください。

sudo gitlab-backup create REPOSITORIES_SERVER_SIDE=true

sudo -u git -H bundle exec rake gitlab:backup:create REPOSITORIES_SERVER_SIDE=true

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

Gitリポジトリを同時にバックアップする

複数のリポジトリのストレージを使用している場合、リポジトリを同時にバックアップまたは復元することで、CPU時間を最大限に活用できます。Rakeタスクのデフォルトの動作を変更するには、次の変数を使用します:

• GITLAB_BACKUP_MAX_CONCURRENCY: 同時にバックアップするプロジェクトの最大数。デフォルトは論理CPUの数です。
• GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY: 各ストレージで同時にバックアップするプロジェクトの最大数。これにより、リポジトリのバックアップを複数のストレージに分散させることができます。デフォルトは2です。

たとえば、リポジトリのストレージが4つある場合は、次のようになります:

sudo gitlab-backup create GITLAB_BACKUP_MAX_CONCURRENCY=4 GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY=1

sudo -u git -H bundle exec rake gitlab:backup:create GITLAB_BACKUP_MAX_CONCURRENCY=4 GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY=1

toolbox:
#...
    extra: {}
    extraEnv:
      GITLAB_BACKUP_MAX_CONCURRENCY: 4
      GITLAB_BACKUP_MAX_STORAGE_CONCURRENCY: 1

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

リポジトリの増分バックアップは、前回のバックアップ以降の変更のみを、各リポジトリのバックアップバンドルにパック化するため、フルリポジトリバックアップよりも高速になる場合があります。増分バックアップアーカイブは互いにリンクされていません。各アーカイブはインスタンスの自己完結型バックアップです。増分バックアップを作成するには、既存のバックアップが必要です。

使用するバックアップを選択するには、PREVIOUS_BACKUP=<backup-id>オプションを使用します。デフォルトでは、バックアップファイルはバックアップIDセクションで説明されている方法で作成されます。BACKUP環境変数を設定して、ファイル名の<backup-id>の部分をオーバーライドできます。

増分バックアップを作成するには、次のコマンドを実行します:

sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<backup-id>

tar形式のバックアップから展開済みの増分バックアップを作成するには、SKIP=tarを使用します:

sudo gitlab-backup create INCREMENTAL=yes SKIP=tar

特定のリポジトリのストレージをバックアップする

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

次に例を示します:

sudo gitlab-backup create REPOSITORIES_STORAGES=storage1,storage2

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

特定のリポジトリをバックアップする

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

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

sudo gitlab-backup create REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

sudo -u git -H bundle exec rake gitlab:backup:create REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

REPOSITORIES_PATHS=group-a SKIP_REPOSITORIES_PATHS=group-a/project_a2 backup-utility --skip db,registry,uploads,artifacts,lfs,packages,external_diffs,terraform_state,ci_secure_files,pages

リモート（クラウド）ストレージにバックアップをアップロードする

バックアップスクリプトで作成された.tarファイルをリモートストレージにアップロードできます。次の例では、ストレージにAmazon S3を使用していますが、Google Cloud StorageやAzureなどの他のクラウドプロバイダー、またはローカルにマウントされた共有を使用することもできます。

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

• Fogライブラリのドキュメント
• その他のストレージプロバイダー
• GitLabオブジェクトストレージガイド
• ローカルにマウントされた共有にアップロードする
• GitLabでのオブジェクトストレージの使用

Amazon S3の使用

Linuxパッケージ（Omnibus）の場合:

1. 次の内容を/etc/gitlab/gitlab.rbに追加します:

   gitlab_rails['backup_upload_connection'] = {
     'provider' => 'AWS',
     'region' => 'eu-west-1',
     # Choose one authentication method
     # IAM Profile
     'use_iam_profile' => true
     # OR AWS Access and Secret key
     'aws_access_key_id' => 'AKIAKIAKI',
     'aws_secret_access_key' => 'secret123'
   }
   gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'
   # Consider using multipart uploads when file size reaches 100 MB. Enter a number in bytes.
   # gitlab_rails['backup_multipart_chunk_size'] = 104857600

2. IAMプロファイル認証方法を使用している場合は、backup-utilityを実行するインスタンスに、次のポリシーが設定されていることを確認してください（<backups-bucket>は正しいバケット名に置き換えます）:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:DeleteObject"
               ],
               "Resource": "arn:aws:s3:::<backups-bucket>/*"
           }
       ]
   }

3. 変更を有効にするには、GitLabを再設定します。

S3暗号化バケット

AWSは、次のサーバー側の暗号化のモードをサポートしています:

• Amazon S3マネージドキー（SSE-S3）
• AWS Key Management Service（SSE-KMS）に保存されたカスタマーマスターキー（CMK）
• カスタマー提供キー（SSE-C）

GitLabでは、任意のモードを使用できます。各モードの設定方法は似ていますが、一部に異なる点があります。

SSE-S3

SSE-S3を有効にするには、バックアップストレージのオプションでserver_side_encryptionフィールドをAES256に設定します。たとえば、Linuxパッケージ（Omnibus）の場合は次のようになります:

gitlab_rails['backup_upload_storage_options'] = {
  'server_side_encryption' => 'AES256'
}

SSE-KMS

SSE-KMSを有効にするには、KMSキーをAmazonリソースネーム（ARN）で指定する必要があります。形式はarn:aws:kms:region:acct-id:key/key-idです。backup_upload_storage_optionsの設定で、次のように設定します:

• server_side_encryptionをaws:kmsに設定します。
• server_side_encryption_kms_key_idをキーのARNに設定します。

たとえば、Linuxパッケージ（Omnibus）の場合は次のようになります:

gitlab_rails['backup_upload_storage_options'] = {
  'server_side_encryption' => 'aws:kms',
  'server_side_encryption_kms_key_id' => 'arn:aws:<YOUR KMS KEY ID>:'
}

SSE-C

SSE-Cでは、次の暗号化オプションを設定する必要があります:

• backup_encryption: AES256。
• backup_encryption_key: エンコードされていない32バイト（256ビット）のキー。このキーが正確に32バイトでない場合、アップロードは失敗します。

たとえば、Linuxパッケージ（Omnibus）の場合は次のようになります:

gitlab_rails['backup_encryption'] = 'AES256'
gitlab_rails['backup_encryption_key'] = '<YOUR 32-BYTE KEY HERE>'

キーにバイナリ文字が含まれておりUTF-8でエンコードできない場合は、代わりにGITLAB_BACKUP_ENCRYPTION_KEY環境変数でキーを指定します。次に例を示します:

gitlab_rails['env'] = { 'GITLAB_BACKUP_ENCRYPTION_KEY' => "\xDE\xAD\xBE\xEF" * 8 }

Digital Ocean Spaces

この例は、アムステルダム（AMS3）のバケットに使用できます:

1. 次の内容を/etc/gitlab/gitlab.rbに追加します:

   gitlab_rails['backup_upload_connection'] = {
     'provider' => 'AWS',
     'region' => 'ams3',
     'aws_access_key_id' => 'AKIAKIAKI',
     'aws_secret_access_key' => 'secret123',
     'endpoint'              => 'https://ams3.digitaloceanspaces.com'
   }
   gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket'

2. 変更を有効にするには、GitLabを再設定します。

Digital Ocean Spacesを使用している場合に400 Bad Request（不正なリクエスト）エラーメッセージが表示される場合は、バックアップ暗号化の使用が原因である可能性があります。Digital Ocean Spacesは暗号化をサポートしていないため、gitlab_rails['backup_encryption']を含む行を削除するかコメントアウトします。

その他のS3プロバイダー

すべてのS3プロバイダーが、Fogライブラリと完全に互換性があるわけではありません。たとえば、アップロードを試みた後に411 Length Required（長さ情報が必要）エラーメッセージが表示された場合は、この問題が原因で、aws_signature_versionの値をデフォルト値から2にダウングレードする必要がある場合があります。

自己コンパイルインストールの場合:

1. home/git/gitlab/config/gitlab.ymlを編集します:

     backup:
       # snip
       upload:
         # Fog storage connection settings, see https://fog.github.io/storage/ .
         connection:
           provider: AWS
           region: eu-west-1
           aws_access_key_id: AKIAKIAKI
           aws_secret_access_key: 'secret123'
           # If using an IAM Profile, leave aws_access_key_id & aws_secret_access_key empty
           # ie. aws_access_key_id: ''
           # use_iam_profile: 'true'
         # The remote 'directory' to store your backups. For S3, this would be the bucket name.
         remote_directory: 'my.s3.bucket'
         # Specifies Amazon S3 storage class to use for backups, this is optional
         # storage_class: 'STANDARD'
         #
         # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional
         #   'encryption' must be set in order for this to have any effect.
         #   'encryption_key' should be set to the 256-bit encryption key for Amazon S3 to use to encrypt or decrypt.
         #   To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` your data.
         # encryption: 'AES256'
         # encryption_key: '<key>'
         #
         #
         # Turns on AWS Server-Side Encryption with Amazon S3-Managed keys (optional)
         # https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html
         # For SSE-S3, set 'server_side_encryption' to 'AES256'.
         # For SS3-KMS, set 'server_side_encryption' to 'aws:kms'. Set
         # 'server_side_encryption_kms_key_id' to the ARN of customer master key.
         # storage_options:
         #   server_side_encryption: 'aws:kms'
         #   server_side_encryption_kms_key_id: 'arn:aws:kms:YOUR-KEY-ID-HERE'

2. 変更を有効にするには、GitLabを再起動します。

Google Cloud Storageを使用する

Google Cloud Storageを使用してバックアップを保存するには、まずGoogleコンソールからアクセスキーを作成する必要があります:

1. Googleのストレージ設定ページに移動します。
2. Interoperability（相互運用性）を選択し、アクセスキーを作成します。
3. Access Key（アクセスキー）とシークレットをメモして、次の設定でこれらの値に置き換えます。
4. バケットの高度な設定で、Access Control（アクセス制御）オプションのSet object-level and bucket-level permissions（オブジェクトレベルおよびバケットレベルの権限を設定）が選択されていることを確認します。
5. バケットがすでに作成されていることを確認します。

Linuxパッケージ（Omnibus）の場合:

1. /etc/gitlab/gitlab.rbを編集します:

   gitlab_rails['backup_upload_connection'] = {
     'provider' => 'Google',
     'google_storage_access_key_id' => 'Access Key',
     'google_storage_secret_access_key' => 'Secret',
   
     ## If you have CNAME buckets (foo.example.com), you might run into SSL issues
     ## when uploading backups ("hostname foo.example.com.storage.googleapis.com
     ## does not match the server certificate"). In that case, uncomment the following
     ## setting. See: https://github.com/fog/fog/issues/2834
     #'path_style' => true
   }
   gitlab_rails['backup_upload_remote_directory'] = 'my.google.bucket'

2. 変更を有効にするには、GitLabを再設定します。

自己コンパイルインストールの場合:

1. home/git/gitlab/config/gitlab.ymlを編集します:

     backup:
       upload:
         connection:
           provider: 'Google'
           google_storage_access_key_id: 'Access Key'
           google_storage_secret_access_key: 'Secret'
         remote_directory: 'my.google.bucket'

2. 変更を有効にするには、GitLabを再起動します。

Azure Blob Storageを使用する

詳細については、Azureパラメータの表を参照してください。

バックアップ用のカスタムディレクトリを指定する

このオプションは、リモートストレージでのみ機能します。バックアップをグループ化する場合は、DIRECTORY環境変数を渡します:

sudo gitlab-backup create DIRECTORY=daily
sudo gitlab-backup create DIRECTORY=weekly

リモートストレージへのバックアップのアップロードをスキップする

リモートストレージにバックアップをアップロードするようGitLabを設定している場合は、SKIP=remoteオプションを使用して、リモートストレージへのバックアップのアップロードをスキップできます。

sudo gitlab-backup create SKIP=remote

sudo -u git -H bundle exec rake gitlab:backup:create SKIP=remote RAILS_ENV=production

ローカルにマウントされた共有にアップロードする

Fog Localストレージプロバイダーを使用して、ローカルにマウントされた共有（例: NFS、CIFS、SMB）にバックアップを送信できます。

これを行うには、次の設定キーを指定する必要があります:

• backup_upload_connection.local_root: バックアップのコピー先であるマウントされたディレクトリ。
• backup_upload_remote_directory: backup_upload_connection.local_rootディレクトリのサブディレクトリ。存在しない場合は作成されます。マウントされたディレクトリのルートにtarballをコピーする場合は、.を使用します。

マウントする際に、local_rootキーに設定したディレクトリは、次のいずれかのユーザーが所有している必要があります:

• gitユーザー。CIFSおよびSMBの場合は、gitユーザーのuid=を指定してマウントします。
• バックアップタスクを実行しているユーザー。Linuxパッケージ（Omnibus）の場合、これはgitユーザーです。

ファイルシステムのパフォーマンスがGitLab全体のパフォーマンスに影響を及ぼす可能性があります。そのため、ストレージにクラウドベースのファイルシステムを使用することはおすすめしません。

競合する設定を回避する

次の設定キーを同じパスに設定しないでください:

• gitlab_rails['backup_path']（自己コンパイルによるインストールの場合はbackup.path）。
• gitlab_rails['backup_upload_connection'].local_root（自己コンパイルによるインストールの場合はbackup.upload.connection.local_root）。

backup_path設定キーは、バックアップファイルのローカルの場所を設定します。upload設定キーは、アーカイブなどの目的で、バックアップファイルを別のサーバーにアップロードする場合に使用することを想定しています。

これらの設定キーが同じ場所に設定されている場合、アップロード先にバックアップがすでに存在するため、アップロード機能は失敗します。この失敗により、アップロード機能はそのバックアップをアップロードの失敗によって残されたファイルと見なし、削除してしまいます。

ローカルにマウントされた共有へのアップロードを設定する

バックアップアーカイブの権限

GitLabによって作成されるバックアップアーカイブ（1393513186_2014_02_27_gitlab_backup.tar）のオーナー/グループは、デフォルトでgit/gitであり、0600権限が付与されています。これは、他のシステムユーザーがGitLabデータを読み取るのを防ぐためです。バックアップアーカイブに異なる権限を設定する必要がある場合は、archive_permissions設定を使用できます。

毎日バックアップを実行するようcronを設定する

**重要:**以下もバックアップすることを忘れないでください:

• GitLabの設定ファイル（）
• SSHホストキー

リポジトリとGitLabメタデータをバックアップするcronジョブをスケジュールできます。

CRON=1の環境設定は、エラーがない場合、すべての進行状況の出力を非表示にするようにバックアップスクリプトに指示します。この方法は、cronスパムを減らせるのでおすすめです。ただし、バックアップの問題をトラブルシューティングする場合は、詳細なログを記録するためにCRON=1を--traceに置き換えてください。

ローカルファイルのバックアップライフタイムを制限する（古いバックアップを削除する）

定期的なバックアップがディスク容量を使い切ってしまわないように、バックアップのライフタイムを制限しておくとよいでしょう。それにより、次回のバックアップタスクの実行時に、backup_keep_timeより古いバックアップは削除されます。

この設定オプションで管理できるのは、ローカルファイルのみです。ユーザーがファイルの一覧表示と削除を行う権限を持っていない可能性があるため、GitLabはサードパーティのオブジェクトストレージに保存されている古いファイルを削除しません。オブジェクトストレージに適切な保持ポリシーを設定することをお勧めします (例: AWS S3)。

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

• カスタムファイル名の設定
• リモートクラウドストレージにバックアップをアップロードする
• AWS S3ライフサイクルポリシー

PgBouncerを使用しているインストール環境でバックアップおよび復元する

PgBouncer経由の接続でGitLabをバックアップまたは復元しないでください。これらのタスクは、必ずPgBouncerを回避し、PostgreSQLプライマリデータベースノードに直接接続して実行する必要があります。そうしないと、GitLabの停止を引き起こす原因となります。

GitLabのバックアップまたは復元タスクをPgBouncerとともに使用すると、次のエラーメッセージが表示されます:

ActiveRecord::StatementInvalid: PG::UndefinedTable

GitLabのバックアップが実行されるたびに、GitLabは500エラーを生成し始め、PostgreSQLのログにはテーブルが存在しないというエラーが記録されます:

ERROR: relation "tablename" does not exist at character 123

これは、タスクがpg_dumpを使用していることが原因です。CVE-2018-1058に対応するために、検索パスをnullに設定し、すべてのSQLクエリでスキーマを明示的に含めています。

トランザクションプーリングモードでPgBouncerを使用すると、接続が再利用されるため、PostgreSQLはデフォルトのpublicスキーマを検索できません。その結果、検索パスがクリアされ、テーブルと列が存在しないかのように見えます。

技術的な参考文献:

• スキーマ処理の実装
• CVE-2018-1058の詳細

PgBouncerを回避する

この問題を修正するには、次の2つの方法があります:

1. 環境変数を使用して、バックアップタスクのデータベース設定をオーバーライドする。
2. ノードを再設定して、PostgreSQLプライマリデータベースノードに直接接続する。

環境変数をオーバーライドする

デフォルトでは、GitLabは設定ファイル（database.yml）に保存されたデータベース設定を使用します。ただし、GITLAB_BACKUP_をプレフィックスとして付けて環境変数を設定することで、バックアップタスクと復元タスクのデータベース設定をオーバーライドできます:

• GITLAB_BACKUP_PGHOST
• GITLAB_BACKUP_PGUSER
• GITLAB_BACKUP_PGPORT
• GITLAB_BACKUP_PGPASSWORD
• GITLAB_BACKUP_PGSSLMODE
• GITLAB_BACKUP_PGSSLKEY
• GITLAB_BACKUP_PGSSLCERT
• GITLAB_BACKUP_PGSSLROOTCERT
• GITLAB_BACKUP_PGSSLCRL
• GITLAB_BACKUP_PGSSLCOMPRESSION

たとえば、Linuxパッケージ（Omnibus）で192.168.1.10とポート5432を使用するようにデータベースのホストとポートをオーバーライドするには、次のコマンドを実行します:

sudo GITLAB_BACKUP_PGHOST=192.168.1.10 GITLAB_BACKUP_PGPORT=5432 /opt/gitlab/bin/gitlab-backup create

GitLabを複数のデータベースで実行している場合は、環境変数にデータベース名を含めることでデータベース設定をオーバーライドできます。たとえば、mainデータベースとciデータベースを異なるデータベースサーバー上でホストしている場合、GITLAB_BACKUP_プレフィックスの後にそれぞれの名前を付加し、PG*の名前はそのままにします:

sudo GITLAB_BACKUP_MAIN_PGHOST=192.168.1.10 GITLAB_BACKUP_CI_PGHOST=192.168.1.12 /opt/gitlab/bin/gitlab-backup create

これらのパラメータの詳細については、PostgreSQLのドキュメントを参照してください。

リポジトリのバックアップと復元におけるgitaly-backup

gitaly-backupバイナリは、バックアップ用Rakeタスクで使用され、Gitalyからのリポジトリのバックアップを作成および復元します。gitaly-backupは、GitLabからGitalyに直接RPCを呼び出す従来のバックアップ方法に代わるものです。

バックアップ用Rakeタスクが、この実行可能ファイルを見つけられる必要があります。ほとんどの場合、バイナリのパスを変更する必要はありません。デフォルトパスの/opt/gitlab/embedded/bin/gitaly-backupで正常に動作するはずです。パスを変更する特別な理由がある場合は、Linuxパッケージ（Omnibus）の設定で変更できます:

1. 次の内容を/etc/gitlab/gitlab.rbに追加します:

   gitlab_rails['backup_gitaly_backup_path'] = '/path/to/gitaly-backup'

2. 変更を有効にするには、GitLabを再設定します。

代替バックアップ戦略

それぞれのデプロイには異なる機能がある可能性があるため、最初にバックアップする必要のあるデータを確認し、それらを活用できるかどうか、またその方法をより深く理解する必要があります。

たとえば、Amazon RDSを使用している場合、その組み込みバックアップおよび復元機能を使用してGitLab PostgreSQLデータベースデータを処理し、バックアップコマンドを使用するときにPostgreSQLデータを除外できます。

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

• バックアップする必要のあるデータ
• PostgreSQLデータベース
• バックアップから特定のデータを除外する
• バックアップコマンド

次のような場合は、バックアップ戦略の一環として、ファイルシステムのデータ転送やスナップショットの使用を検討してください:

• GitLabインスタンスに大量のGitリポジトリデータが含まれており、GitLabのバックアップスクリプトでは処理速度が遅すぎる。
• GitLabインスタンスに多くのフォークされたプロジェクトがあり、標準のバックアップタスクではそれらすべてのGitデータが重複してバックアップされる。
• GitLabインスタンスに問題があり、通常のバックアップタスクとインポート用Rakeタスクを使用できない。

ファイルシステムのデータ転送またはスナップショットの使用を検討する場合は、次の点に注意してください:

• これらの方法を使用して、異なるオペレーティングシステム間で移行しないでください。移行元と移行先のオペレーティングシステムは、可能な限り同じ環境にそろえる必要があります。たとえば、UbuntuからRHELへの移行にはこれらの方法を使用しないでください。
• データの整合性は非常に重要です。ファイルシステムの転送（rsyncなど）やスナップショット作成を行う前に、GitLab（sudo gitlab-ctl stop）を停止する必要があります。これにより、メモリ内のすべてのデータがディスクにフラッシュされます。GitLabは複数のサブシステム（Gitaly、データベース、ファイルストレージ）で構成されており、それぞれ独自のバッファー、キュー、ストレージレイヤーを持っています。GitLabのトランザクションはこれらのサブシステム間にまたがる可能性があるため、トランザクションの一部が異なるパスを通ってディスクに書き込まれる場合があります。稼働中のシステムでファイルシステムの転送やスナップショットを実行すると、メモリに残っているトランザクションの一部をキャプチャできません。

例: Amazon Elastic Block Store（EBS）

• Linuxパッケージ（Omnibus）を使用するGitLabサーバーが、Amazon AWSでホストされています。
• ext4ファイルシステムを使用しているEBSドライブが、/var/opt/gitlabにマウントされています。
• この場合、EBSスナップショットを作成してアプリケーションのバックアップを作成できます。
• このバックアップには、すべてのリポジトリ、アップロード、PostgreSQLのデータが含まれます。

例: Logical Volume Manager（LVM）スナップショット+ rsync

• Linuxパッケージ（Omnibus）を使用しているGitLabサーバーで、LVM論理ボリュームが/var/opt/gitlabにマウントされています。
• rsyncを使用して/var/opt/gitlabディレクトリをレプリケートしても、rsyncの実行中に変更されるファイルが多すぎるため、信頼できません。
• そのため、rsyncで/var/opt/gitlabをレプリケートする代わりに、一時的なLVMスナップショットを作成し、/mnt/gitlab_backupに読み取り専用ファイルシステムとしてマウントします。
• これで、長時間実行されるrsyncジョブを実行して、リモートサーバー上に一貫性のあるレプリカを作成できるようになります。
• このレプリカには、すべてのリポジトリ、アップロード、PostgreSQLのデータが含まれます。

仮想サーバー上でGitLabを実行している場合は、GitLabサーバー全体の仮想マシン（VM）スナップショットを作成できる場合もあります。ただし、仮想マシン（VM）スナップショットを作成するにはサーバーをシャットダウンしなければならないことが多くあります。そのため、このソリューションは実用性に制約があります。

リポジトリデータを個別にバックアップする

まず、リポジトリをスキップして、既存のGitLabデータを確実にバックアップします:

sudo gitlab-backup create SKIP=repositories

sudo -u git -H bundle exec rake gitlab:backup:create SKIP=repositories RAILS_ENV=production

ディスク上のGitリポジトリデータを手動でバックアップするには、複数の戦略が考えられます:

• 前述の例のように、Amazon EBSドライブのスナップショットやLVMスナップショット+ rsyncなど、スナップショットを使用する。
• GitLab Geoを使用し、Geoセカンダリサイトのリポジトリデータに依存する。
• 書き込みを防止し、Gitリポジトリデータをコピーする。
• リポジトリを読み取り専用としてマークし、オンラインバックアップを作成する（実験的機能）。

書き込みを防止し、Gitリポジトリデータをコピーする

Gitリポジトリは、一貫した方法でコピーする必要があります。同時書き込み操作中にGitリポジトリをコピーした場合、不整合や破損の問題が発生する可能性があります。これにより、リポジトリの破損、コミットの欠落、または不完全なバックアップデータが発生する可能性があります。

Gitリポジトリデータへの書き込みを防ぐには、次の2つの方法があります:

• メンテナンスモードを使用して、GitLabを読み取り専用状態にする。

• リポジトリをバックアップする前に、すべてのGitalyサービスを停止して、明示的にダウンタイムを設ける:

  sudo gitlab-ctl stop gitaly
  # execute git data copy step
  sudo gitlab-ctl start gitaly

コピー対象のデータへの書き込みが防止されている限り（不整合や破損の問題を防ぐため）、任意の方法でGitリポジトリデータをコピーできます。優先度と安全性の順に、推奨される方法を示します:

1. rsyncをアーカイブモード、削除オプション、チェックサムオプション付きで使用する。次に例を示します:

   rsync -aR --delete --checksum source destination # be extra safe with the order as it will delete existing data if inverted

2. tarパイプを使用して、リポジトリのディレクトリ全体を別のサーバーまたは場所にコピーする。

3. sftp、scp、cpなど、その他のコピー方法を使用する。

リポジトリを読み取り専用としてマークし、オンラインバックアップを作成する（実験的機能）

インスタンス全体のダウンタイムを必要とせずにリポジトリをバックアップする方法の1つは、基盤となるデータをコピーする間、プログラムでプロジェクトを読み取り専用としてマークすることです。

この方法には、いくつかの欠点があります:

• リポジトリが読み取り専用になる時間は、リポジトリのサイズが大きくなるにつれて長くなります。
• 各プロジェクトを読み取り専用としてマークするため、バックアップの完了までの時間が長くなり、不整合が発生する可能性があります。たとえば、最初にバックアップされるプロジェクトと最後にバックアップされるプロジェクトの間で、利用できる最終データの日付が一致しない可能性があります。
• プールリポジトリに対する潜在的な変更を防ぐため、フォークネットワークに含まれるプロジェクトのバックアップ中は、フォークネットワーク全体を完全に読み取り専用にする必要があります。

Geoチームの手順書プロジェクトには、このプロセスの自動化を試みる実験的なスクリプトがあります。