コンテナレジストリのメタデータデータベース

メタデータデータベースは、コンテナレジストリにいくつかの機能拡張を提供します。それにより、パフォーマンスが向上し、新機能が追加されます。レジストリメタデータデータベース機能のGitLab Self-Managedリリースの作業は、エピック5521で追跡されます。

デフォルトでは、コンテナレジストリはオブジェクトストレージまたはローカルファイルシステムを使用して、コンテナイメージに関連するメタデータを保持します。このメタデータを保存する方法では、特にタグをリストするときなど、複数のイメージにまたがるデータの場合に、データへのアクセス効率が制限されます。データベースを使用してこのデータを保存することで、停止時間なしで古いデータを自動的に削除するオンラインガベージコレクションなど、多くの新機能が利用可能になります。

このデータベースは、レジストリですでに使用されているストレージと連携して動作しますが、オブジェクトストレージまたはファイルシステムを置き換えるものではありません。メタデータをメタデータデータベースにインポートした後でも、ストレージソリューションの追跡を継続する必要があります。

Helm Chartのインストールについては、Helm Chartのドキュメントのコンテナレジストリメタデータデータベースの管理を参照してください。

機能拡張

メタデータデータベースのアーキテクチャは、従来のメタデータストレージでは利用できないパフォーマンスの改善、バグ修正、および新機能をサポートしています。これらの機能拡張には以下が含まれます:

• 自動オンラインガベージコレクション
• リポジトリ、プロジェクト、およびグループのストレージ使用量の表示
• イメージ署名
• リポジトリの移動と名前変更
• 保護タグ
• クリーンアップポリシーのパフォーマンス改善により、大規模なリポジトリのクリーンアップを正常に実行できるようになります
• リポジトリタグのリスト表示のパフォーマンスが向上
• タグ公開タイムスタンプの追跡と表示（イシュー290949を参照）
• 名前以外の追加の属性によるリポジトリタグの並べ替え

従来のメタデータストレージの技術的な制約により、新機能はメタデータデータベースバージョンでのみ実装されます。セキュリティ以外のバグ修正は、メタデータデータベースバージョンに限定される場合があります。

既知の制限事項

• 既存のレジストリへのメタデータインポートには、読み取り専用の時間が必要です。
• バージョンをアップグレードする場合、18.3より前のレジストリの通常のスキーマとデプロイ後のデータベースの移行は、手動で実行する必要があります。
• マルチノードLinuxパッケージ環境では、レジストリのアップグレード中の停止時間ゼロは保証されません。
• 既存のレジストリのメタデータインポート中、イメージタグのcreatedAtとpublishedAtのタイムスタンプ値はインポート日に設定されます。これは、整合性を確保するために意図的に行われます。従来のレジストリがすべてのイメージのタグ公開日を収集しないためです。一部のイメージのメタデータにはビルド日が含まれていますが、そうでないイメージも多くあります。詳細については、イシュー1384を参照してください。

メタデータデータベース機能のサポート

既存のレジストリからメタデータデータベースにメタデータをインポートし、オンラインガベージコレクションを使用できます。

一部のデータベース対応機能はGitLab.comでのみ有効になり、レジストリデータベースの自動データベースプロビジョニングは利用できません。コンテナレジストリデータベースに関連する機能のステータスについては、フィードバックイシューの機能サポートテーブルを確認してください。

Linuxパッケージインストールでのメタデータデータベースの有効化

前提条件:

• GitLab 17.5が最小必須バージョンですが、GitLab 18.3以降をお勧めします。改善と設定が容易になっているためです。
• バージョン要件に適合するPostgreSQLデータベース。レジストリノードからアクセス可能なものである必要があります。
• 外部データベースを使用する場合は、最初に外部データベース接続をセットアップする必要があります。詳細については、外部データベースの使用を参照してください。

はじめに

• データベースを有効にした後は、継続してそのデータベースを使用する必要があります。データベースはレジストリメタデータのソースになりました。この時点より後に無効にすると、データベースがアクティブな間、レジストリはそこに書き込まれたすべてのイメージの表示レベルを失います。
• オフラインガベージコレクションは不要になりました。GitLabに付属しているガベージコレクションコマンドは、データベースが有効になっている場合は安全に終了します。しかし、アップストリームレジストリによって提供されるコマンドなど、サードパーティのコマンドの場合は、タグ付きイメージに関連付けられたデータを削除します。
• オフラインガベージコレクションを自動化していないことを確認してください。サードパーティのコマンドを使用している場合は、特に確認してください。
• 最初にレジストリのストレージを削減することで、プロセスを高速化できます。
• 可能であれば、コンテナレジストリデータをバックアップします。

新しいインストールでのデータベースの有効化

コンテナレジストリにデータを書き込んだことのないインストールの場合、インポートは必要ありません。データをレジストリに書き込む前に、データベースを有効にする必要があります。

詳細については、新しいインストールの手順を参照してください。

既存のレジストリのデータベースの有効化

既存のコンテナレジストリメタデータを、ワンステップインポート方法または3ステップインポート方法のいずれかを使用してインポートできます。インポートの期間に影響を与える要因が、以下のとおりいくつかあります:

• レジストリ内のタグ付きイメージの数。
• 既存のレジストリデータのサイズ。
• PostgreSQLインスタンスの仕様。
• 実行中のレジストリインスタンスの数。
• レジストリ、PostgreSQL、設定されたストレージ間のネットワークレイテンシー。

インポート前に、準備として以下を行う必要はありません:

• 追加のオブジェクトストレージまたはファイルシステム領域の割り当て: ただし、インポート処理ではこのストレージに対して大きな書き込みは行われません。
• オフラインガベージコレクションの実行: この操作自体に害はありませんが、オフラインガベージコレクションはインポート処理を短縮する効果はほとんどなく、コマンドの実行に要する時間を取り戻すほどの効果はありません。

適切なインポート方法の選択方法

定期的にオフラインガベージコレクションを実行する場合は、ワンステップインポート方式を使用します。この方法は、処理にかかる時間がほぼ同程度であり、3ステップのインポート方法と比べて操作がより簡単です。

レジストリが大きすぎてオフラインガベージコレクションを定期的に実行できない場合は、3ステップのインポート方式を使用すると、読み取り専用時間を大幅に短縮できます。

外部データベースを使用する場合は、移行パスに進む前に、外部データベース接続をセットアップしてください。

詳細については、外部データベースの使用を参照してください。

インポートの中断からの復元

過去72時間以内に事前インポートしたリポジトリをスキップして、中断したインポートを再開します。リポジトリは、次のいずれかによって事前インポートされます:

• 3ステップのインポートプロセスのステップ1を完了する
• 1ステップのインポートプロセスを完了する

中断したインポートを復元するには、--pre-import-skip-recentフラグを設定します。デフォルトは72時間です。

例:

# Skip repositories imported within 6 hours from the start of the import command
--pre-import-skip-recent 6h

# Disable skipping behavior
--pre-import-skip-recent 0

有効な期間単位の詳細については、Go言語のduration文字列を参照してください。

インポート後

レジストリストレージの減少を確認するには、インポート後約48時間かかる場合があります。これはオンラインガベージコレクションの正常かつ想定された動作です。この遅延は、オンラインガベージコレクションがイメージのプッシュ処理に干渉しないようにするためのものです。オンラインガベージコレクターの進捗とヘルスをモニタリングする方法については、オンラインガベージコレクションのモニタリングセクションを確認してください。

Preferモード

Preferモードは、既存のレジストリがまだデータベースにインポートされていない場合に、レジストリがレガシーメタデータストレージにフォールバックできるようにするメタデータデータベースの設定オプションです。

Preferモードを有効にする

Preferモードを有効にするには:

1. /etc/gitlab/gitlab.rbで、database.enabledをtrueまたはfalseの代わりに"prefer"に設定します:

   registry['database'] = {
     'enabled' => 'prefer',
     'host' => '<your_database_host>',
     'port' => 5432,
     'user' => '<your_database_user>',
     'password' => '<your_database_password>',
     'dbname' => '<your_database_name>',
   }

2. ファイルを保存し、GitLabを再設定します。

GitLabを再設定すると、レジストリは、ファイルシステムまたはデータベースへの以前の書き込みを追跡するロックファイルに基づいて、起動時に使用するメタデータバックエンドを評価します:

• ファイルシステムのロックファイルが存在する場合: レジストリには既存のファイルシステムメタデータがあります。レガシーメタデータストレージにフォールバックし、警告をログに記録します。メタデータインポートが完了するまで、レジストリはenabled: falseと同一に動作します。
• データベースのロックファイルが存在する場合: レジストリはすでにデータベースを使用しています。enabled: trueと同一に、正常にデータベースに接続します。
• ロックファイルが存在しない場合: レジストリは新規インストールです。起動するには設定済みで到達可能なデータベースが必要であり、レガシーストレージへのフォールバックは行いません。
• 両方のロックファイルが存在する場合: レジストリは起動を拒否します。これは、手動で解決する必要がある設定エラーを示しています。

フォールバックの決定は起動時に一度だけ行われ、レジストリの実行中は変更されません。フォールバック後にデータベースへの自動再試行または再接続はありません。フォールバック後にファイルシステムからデータベースモードに移行するには、標準のメタデータインポートを完了し、レジストリを再起動します。

どのメタデータバックエンドがアクティブかを確認する

レジストリが使用しているメタデータバックエンドを確認するには、次のいずれかの方法を使用します。

レジストリAPI応答ヘッダーを確認する

1. レジストリ/v2/エンドポイントにリクエストを送信します:

   curl --silent --head "https://registry.example.com/v2/" | grep --ignore-case gitlabcontainer-registry-database-enabled

2. gitlab-container-registry-database-enabled応答ヘッダーを検査します:

   • trueの値は、レジストリがメタデータデータベースを使用していることを意味します。
   • falseの値は、レガシーファイルシステムストレージを使用していることを意味します。

ディスク上のロックファイルを確認する

ディスク上のロックファイルを確認するには、<rootdirectory>/docker/registry/lockfiles/にある設定済みのストレージバックエンドでこれらのファイルを探します:

• database-in-use: レジストリはメタデータデータベースを使用しています。
• filesystem-in-use: レジストリはレガシーファイルシステムストレージを使用しています。

両方のロックファイルが存在する場合、レジストリは無効な状態であり、起動しません。

レジストリのログを確認する

レジストリは、起動時に選択するメタデータバックエンドをログに記録します。

レジストリのログを確認するには、次のいずれかのメッセージを探します:

• レジストリがレガシーストレージにフォールバックする場合 (Preferモードのみ):

  database prefer mode enabled, but found filesystem metadata: falling back to legacy metadata

• レジストリがデータベースに接続する場合:

  using the metadata database

データベースの移行

コンテナレジストリは、2種類の移行をサポートしています:

• 通常のスキーマ移行: 新しいアプリケーションコードをデプロイする前に実行する必要があるデータベース構造の変更、いわゆるプレデプロイ後の移行です。これらの処理はデプロイの遅延を防ぐため、数分以内で完了することが望まれます。
• デプロイ後の移行: アプリケーションの稼働中に実行できるデータベース構造の変更です。大規模なテーブルへのインデックス作成など、時間のかかる処理に使用され、起動時の遅延やアップグレード時の長時間停止を回避できます。

デフォルトでは、レジストリは通常のスキーマ移行とポストデプロイ後の移行の両方を同時に適用します。アップグレード時のダウンタイムを短縮するには、ポストデプロイ後の移行をスキップし、アプリケーションの起動後に手動で実行することができます。

データベース移行の適用

オンラインガベージコレクションのモニタリング

インポート処理後に実行される最初のオンラインガベージコレクションは、インポートされたイメージの数に応じて所要時間が異なります。この期間中は、オンラインガベージコレクションの効率性と健全性を監視することを推奨します。

データベースパフォーマンスのモニタリング

インポートが完了すると、ガベージコレクションのキューが処理される間、データベースに高負荷がかかる期間が発生します。この高負荷は、オンラインガベージコレクターがキューに登録されたタスクを処理する際に、多数の個別データベース呼び出しを行うことによって生じます。

PostgreSQLとレジストリのログにエラーまたは警告がないか定期的に確認してください。レジストリログでは、component=registry.gc.*でフィルタリングされたログに特に注意してください。

メトリクスの追跡

PrometheusやGrafanaなどのモニタリングツールを使用してガベージコレクションメトリクスを視覚化および追跡し、registry_gc_*のプレフィックスが付いたメトリクスに焦点を当てます。これらには、削除対象としてマークされたオブジェクトの数、正常に削除されたオブジェクト、実行間隔、および期間が含まれます。Prometheusを有効にする方法については、レジストリデバッグサーバーを有効にするを参照してください。

タスクキューのモニタリング

Blobおよびマニフェストのガベージコレクションタスクキューのヘルスとステータスをモニタリングします。

オンラインガベージコレクションのヘルスをチェックします

sudo gitlab-ctl registry-database gc-stats

=== Blob Review Queue ===

Tasks Pending Removal: 42
Tasks ready for GC review (review_after has passed).

┌───────────────────────────────────────────────────────────────────┬─────────────────────┬─────────────────┐
│                              DIGEST                               │    REVIEW AFTER     │      EVENT      │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼─────────────────┤
│ sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22e  │ 2026-01-16 21:56:13 │ blob_upload     │
│ sha256:b4f5e6d7c8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2 │ 2026-01-16 19:56:13 │ manifest_delete │
│ sha256:c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3 │ 2026-01-16 17:56:13 │ layer_delete    │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴─────────────────┘

Long Overdue Tasks: 5
Tasks pending longer than configured delay - may need attention.

┌───────────────────────────────────────────────────────────────────┬─────────────────────┬──────────────┬─────────┐
│                              DIGEST                               │    REVIEW AFTER     │    EVENT     │ OVERDUE │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼──────────────┼─────────┤
│ sha256:d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4 │ 2026-01-11 23:56:13 │ blob_upload  │ 4d 0h   │
│ sha256:e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5 │ 2026-01-13 23:56:13 │ layer_delete │ 2d 0h   │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴──────────────┴─────────┘

High Retry Tasks: 2
Tasks with >10 review attempts - may indicate persistent issues.

┌───────────────────────────────────────────────────────────────────┬─────────────────────┬─────────────────┬─────────┐
│                              DIGEST                               │    REVIEW AFTER     │      EVENT      │ RETRIES │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼─────────────────┼─────────┤
│ sha256:f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 │ 2026-01-17 00:56:13 │ blob_upload     │ 15      │
│ sha256:a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 │ 2026-01-17 01:56:13 │ manifest_delete │ 12      │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴─────────────────┴─────────┘

=== Manifest Review Queue ===

Tasks Pending Removal: 128
Tasks ready for GC review (review_after has passed).

┌───────────────┬─────────────┬─────────────────────┬──────────────────────┐
│ REPOSITORY ID │ MANIFEST ID │    REVIEW AFTER     │        EVENT         │
├───────────────┼─────────────┼─────────────────────┼──────────────────────┤
│ 1001          │ 12345       │ 2026-01-16 22:56:13 │ tag_delete           │
│ 1002          │ 67890       │ 2026-01-16 20:56:13 │ manifest_upload      │
│ 1003          │ 11111       │ 2026-01-16 18:56:13 │ tag_switch           │
│ 2001          │ 22222       │ 2026-01-16 16:56:13 │ manifest_list_delete │
└───────────────┴─────────────┴─────────────────────┴──────────────────────┘

Long Overdue Tasks: 8
Tasks pending longer than configured delay - may need attention.

┌───────────────┬─────────────┬─────────────────────┬─────────────────┬─────────┐
│ REPOSITORY ID │ MANIFEST ID │    REVIEW AFTER     │      EVENT      │ OVERDUE │
├───────────────┼─────────────┼─────────────────────┼─────────────────┼─────────┤
│ 3001          │ 33333       │ 2026-01-12 23:56:13 │ tag_delete      │ 3d 0h   │
│ 3002          │ 44444       │ 2026-01-14 23:56:13 │ manifest_delete │ 1d 0h   │
└───────────────┴─────────────┴─────────────────────┴─────────────────┴─────────┘

High Retry Tasks: 3
Tasks with >10 review attempts - may indicate persistent issues.

┌───────────────┬─────────────┬─────────────────────┬─────────────────┬─────────┐
│ REPOSITORY ID │ MANIFEST ID │    REVIEW AFTER     │      EVENT      │ RETRIES │
├───────────────┼─────────────┼─────────────────────┼─────────────────┼─────────┤
│ 4001          │ 55555       │ 2026-01-17 00:26:13 │ tag_delete      │ 18      │
│ 4002          │ 66666       │ 2026-01-17 00:41:13 │ manifest_upload │ 11      │
└───────────────┴─────────────┴─────────────────────┴─────────────────┴─────────┘

SELECT
  repository_id,
  manifest_id,
  ROUND(
    EXTRACT(
      EPOCH
      FROM
        AGE(NOW(), review_after)
    ) / 3600
  ) AS hours_eligible_for_review,
  review_count as failed_review_attempts,
  event
FROM
  gc_manifest_review_queue
WHERE
  review_after < NOW() - INTERVAL '24 hours'
  OR review_count > 10
LIMIT
  20;

SELECT
  substring(encode(digest, 'hex'), 3) AS digest,
  ROUND(
    EXTRACT(
      EPOCH
      FROM
        AGE(NOW(), review_after)
    ) / 3600
  ) AS hours_eligible_for_review,
  review_count as failed_review_attempts,
  event
FROM
  gc_blob_review_queue
WHERE
  review_after < NOW() - INTERVAL '24 hours'
  OR review_count > 10
LIMIT
  20;

SELECT COUNT(*) FROM gc_blob_review_queue WHERE review_after < NOW();
SELECT COUNT(*) FROM gc_manifest_review_queue WHERE review_after < NOW();

一般的に、レビューの準備ができているアイテムの数は比較的少なく、多くの場合ゼロに近づくはずです。しかし、次のような場合にはさらに多くなる可能性があります:

• インポートが24〜48時間前に開始された場合。
• 大量のタグが削除されたか、コンテナリポジトリが削除された場合。
• オンラインガベージコレクションが長期間無効になっていた場合。

再試行を伴うタスクがある場合、または期限が大幅に過ぎているタスクがある場合は、レジストリのログでガベージコレクション関連のメッセージを確認してください。component="registry.gc.*でエントリをフィルタリングし、エラーメッセージを調査します。

トラブルシューティングの前に確認する

GCキューサイズ

gc_manifest_review_queueとgc_blob_review_queueの未フィルタ状態でのサイズは、オンラインガベージコレクターのヘルスを示す適切な指標ではありません。これらのキューには常に新しいエントリが追加されるため、アクティブなレジストリではこれらのキューが完全にクリアされることはありません。

さらに、これらのキュー内のすべてのアイテムがストレージから削除されるわけではありません。これらのキューの詳細については、オンラインガベージコレクションの仕様を参照してください。

レビューの準備ができている大量のタスク

レビュー対象となっているタスクが大量に存在していても、必ずしも問題があるとは限りません。ガベージコレクターが、一時的なアクティビティの増加によって発生したアイテムを処理している最中である可能性があります。

古いタスクがいくつかある

同様に、これらのタスクのcreated_at日付だけでは、良好なヘルスインジケータとは言えません。イベントが同じblobまたはマニフェストをキューに追加すると、既存のタスクのreview_afterが更新され、レビューが延期されます。重複タスクは作成されません。

これは何度でも発生する可能性があるため、数か月前に作成されたタスクがあっても心配する必要はありません。

ガベージコレクターワーカー間隔の調整

レビューの対象となるタスクの数が依然として多く、ガベージコレクションblobまたはマニフェストワーカーの実行頻度を上げたい場合は、間隔設定をデフォルト（5s）から1sに更新します:

registry['gc'] = {
  'blobs' => {
    'interval' => '1s'
  },
  'manifests' => {
    'interval' => '1s'
  }
}

インポートの負荷がクリアされたら、データベースとレジストリインスタンスで不要なCPU負荷を回避するために、長期的にこれらの設定を微調整する必要があります。パフォーマンスとリソースの使用量のバランスを取る値まで、徐々に間隔を大きくすることができます。

データ整合性の検証

インポート後にデータの整合性を確保するには、crane validateツールを使用します。このツールは、コンテナレジストリ内のすべてのイメージレイヤーとマニフェストにアクセスでき、正しくリンクされていることを確認します。crane validateを実行して、レジストリ内のイメージが完全でアクセス可能であること、インポートが成功したことを確認します。

クリーンアップポリシーのレビュー

イメージのほとんどにタグが付けられている場合、ガベージコレクションはタグ付けされていないイメージのみを削除するため、ストレージスペースは大幅に削減されません。

クリーンアップポリシーを実装して不要なタグを削除すると、最終的にガベージコレクションとストレージ容量の回復により、イメージが削除されます。

外部データベースの使用

デフォルトでは、GitLab 18.3以降では、コンテナレジストリメタデータ用のメインGitLabデータベース内に論理データベースが事前プロビジョニングされます。ただし、レジストリをスケールする場合は、コンテナレジストリ専用の外部データベースを使用することをお勧めします。

ステップ

• 外部データベースを作成します。

その後、デフォルトデータベースと同じ手順に従って、独自のデータベース値を代入します。データベースが無効になっている状態で開始し、指示に従ってデータベースを有効および無効にするように注意してください:

registry['database'] = {
  'enabled' => false,
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

メタデータベースを使用したバックアップ

メタデータデータベースが有効になっている場合、バックアップにはレジストリストレージバックエンドとデータベースの両方を含める必要があります。

バックアップ方法はストレージの種類によって異なります:

• ローカルファイルシステムストレージ: gitlab-backupは自動的にレジストリを含めます。
• オブジェクトストレージ: オブジェクトストレージは別途バックアップする必要があります。

一貫性のあるレジストリの状態を確保するため、ストレージとデータベースのバックアップは可能な限り同時に行う必要があります。レジストリを復元するには、両方のバックアップを適用する必要があります。

自動バックアップ

GitLab 18.10以降では、gitlab-backup createとgitlab-backup restoreは、メタデータデータベースが設定されている場合、自動的にレジストリメタデータデータベースを含めます。Helmチャート（Kubernetes）のインストールでは、backup-utilityも同様に動作します。

メタデータデータベースはgitlab.rbまたはHelmのvaluesファイルで設定する必要があります。

追加の設定は必要ありません。バックアップツールは、既存の設定からレジストリデータベースの接続設定を読み取ります。

バックアップRakeタスクを直接呼び出す場合、バックアップを実行するノードで次の環境変数を設定する必要があります:

バックアップRakeタスクは、次のいずれかの認証情報を検出すると、レジストリデータベースバックアップをアクティブ化します:

• REGISTRY_DATABASE_PASSWORD
• REGISTRY_DATABASE_SSLCERT
• REGISTRY_DATABASE_SSLKEY
• REGISTRY_DATABASE_SSLROOTCERT

認証情報がない場合、レジストリデータベースはバックアップに含まれません。復元するときにも同じ環境変数を設定する必要があります。

手動バックアップ

GitLab 18.9以前を使用している場合、またはレジストリデータベースのバックアップを個別に管理したい場合は、pg_dumpやpg_restoreのような標準的なPostgreSQLツールを使用して、レジストリデータベースを個別にバックアップおよび復元することができます。

Helmチャート（Kubernetes）のバックアップと復元する

Helmチャート（Kubernetes）のデプロイでは、バックアップおよび復元する操作専用のデータベース認証情報を使用して、ツールボックスポッドを設定します。2つの個別のPostgreSQLユーザーが必要です:

• バックアップユーザーには読み取り専用の権限が必要です。
• 復元するユーザーには書き込み権限が必要です。

必要な操作に応じて、どちらか一方または両方のユーザーを設定します。

開始する前に、registry.database.enabled: trueを設定してコンテナレジストリメタデータデータベースを有効にします。

Kubernetesシークレットを作成する

デプロイする前に、Kubernetesシークレットを手動で作成する必要があります。チャートはこのシークレットを自動生成しません。

例えば、バックアップと復元するの両方のパスワードを持つシークレットを作成するには:

kubectl create secret generic my-registry-db-password-secret \
  --from-literal=backupPassword="BACKUP_USER_PASSWORD" \
  --from-literal=restorePassword="RESTORE_USER_PASSWORD"

レジストリデータベース認証情報を設定する

必要なYAMLをHelmのvalues.yamlに追加して、バックアップユーザーと復元するユーザーを設定します。設定設定の定義については、次の表を参照してください。

次の例は、バックアップユーザーと復元するユーザーの両方を設定します:

gitlab:
  toolbox:
    backups:
      registry:
        database:
          # PostgreSQL username for backing up the registry database
          backupUser: "registry_backup"
          # PostgreSQL username for restoring the registry database
          restoreUser: "registry_restore"
          password:
            # Name of the Kubernetes Secret containing the passwords
            secret: "my-registry-db-password-secret"
            # Key in the Secret for the backup user's password
            backupPasswordKey: "backupPassword"
            # Key in the Secret for the restore user's password
            restorePasswordKey: "restorePassword"

backupUserまたはrestoreUserが設定されていない場合、レジストリデータベースバックアップは静かにスキップされ、ツールボックスポッドは正常に動作します。

PostgreSQLユーザー権限

バックアップユーザーには、レジストリデータベースをダンプするための読み取り専用アクセスが必要です。復元するユーザーには、それを復元するためのスーパーユーザー権限が必要です。

Linuxパッケージインストールの場合、database_backup_username、database_backup_password、database_restore_username、およびdatabase_restore_passwordが設定されると、これらのユーザーと権限が自動的に作成されます。

自己コンパイルまたは外部データベースインストールの場合は、ユーザーを手動で作成し、権限を付与します:

-- Create the backup user with minimal privileges for pg_dump.
-- The registry database uses both the 'public' and 'partitions' schemas.
CREATE ROLE registry_backup WITH LOGIN PASSWORD 'password'
  NOINHERIT NOCREATEDB NOSUPERUSER NOREPLICATION;

GRANT CONNECT ON DATABASE registry TO registry_backup;

-- Grant read-only access on both schemas
GRANT USAGE ON SCHEMA public TO registry_backup;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO registry_backup;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
  GRANT SELECT ON TABLES TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
  GRANT SELECT ON SEQUENCES TO registry_backup;

GRANT USAGE ON SCHEMA partitions TO registry_backup;
GRANT SELECT ON ALL TABLES IN SCHEMA partitions TO registry_backup;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA partitions TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
  GRANT SELECT ON TABLES TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
  GRANT SELECT ON SEQUENCES TO registry_backup;

-- Create the restore user with superuser privileges.
-- SUPERUSER is required for database restore operations because the
-- restore process must SET ROLE to the registry owner and
-- CREATE TRIGGER on all tables.
CREATE ROLE registry_restore WITH LOGIN PASSWORD 'password' SUPERUSER;

認証情報ボリュームワークフロー

設定すると、チャートはツールボックスデプロイとバックアップCronJobの両方で/etc/gitlab/registry-db/にマウントされたボリュームを作成します。ボリュームは読み取り専用で、以下が含まれます:

• 接続パラメータ: レジストリチャートによって作成されたConfigMapで、データベースホスト、ポート、名前、SSLモード、および接続タイムアウトが含まれています。
• バックアップおよび復元するユーザー名: 設定されたbackupUserおよびrestoreUserを含むツールボックスチャートによって作成されたConfigMap。
• パスワード: バックアップと復元するのパスワードを含むユーザー提供のKubernetesシークレット。

ツールボックスポッド内のbackup-utilityはこれらのファイルを読み取り、レジストリメタデータデータベースをバックアップおよび復元する操作に含めます。

必要な認証情報ファイルが不足している場合、backup-utilityは警告をログに記録し、他のリソースのバックアップを続行します。

相互TLSの制限

PostgreSQLでの相互TLS認証用のSSL証明書パスは、SSLがグローバルに設定されている場合（global.psql.ssl）にのみ含まれます。SSLがレジストリサブチャートレベル（registry.database.ssl）でのみ設定されている場合、その設定はツールボックスに渡されません。

Geoに関する考慮事項

コンテナレジストリでGeoを使用する場合、各サイトでレジストリ用に個別のデータベースとオブジェクトストレージのスタックを設定する必要があります。各サイトのレジストリデータベースとオブジェクトストレージを個別にバックアップします。Geoはサイト間でレジストリデータベースをレプリケートしません。

レジストリのダウングレード

インポートが完了した後、レジストリを以前のバージョンにダウングレードするには、目的のバージョンのバックアップに復元してダウングレードする必要があります。

Geoを使用したデータベースアーキテクチャ

コンテナレジストリでGitLab Geoを使用する場合は、サイトごとにレジストリ用に個別のデータベースとオブジェクトストレージスタックを構成する必要があります。コンテナレジストリへのGeoレプリケーションは、データベースレプリケーションではなく、レジストリ通知から生成されたイベントを使用します。

前提条件

各Geoサイトには、サイトごとに固有の以下のリソースが必要です:

1. コンテナレジストリデータベース用のPostgreSQLインスタンス。
2. コンテナレジストリ用のオブジェクトストレージインスタンス。
3. 上記のサイト固有リソースを使用するように構成されたコンテナレジストリ。

この図は、データフローと基本的なアーキテクチャを示しています:

%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TB
    accTitle: Geo architecture for the container registry metadata database
    accDescr: The primary site sends events to the secondary site through the GitLab Rails notification system for Geo replication.

    subgraph "Primary site"
        P_Rails[GitLab Rails]
        P_Reg[Container registry]
        P_RegDB[(Registry database)]
        P_Obj[(Object storage)]
        P_Reg --> P_RegDB
        P_RegDB --> P_Obj
    end

    subgraph "Secondary site"
        S_Rails[GitLab Rails]
        S_Reg[Container registry]
        S_RegDB[(Registry database)]
        S_Obj[(Object storage)]
        S_Reg --> S_RegDB
        S_RegDB --> S_Obj
    end

    P_Reg -- "Notifications" --> P_Rails
    P_Rails -- "Events" --> S_Rails
    S_Rails --> S_Reg

各サイトで個別のデータベースインスタンスを使用してください。理由は次のとおりです:

1. メインのGitLabデータベースは、読み取り専用としてセカンダリサイトにレプリケートされます。
2. このレプリケーションは、レジストリデータベースに対して選択的に無効にすることはできません。
3. コンテナレジストリは、両方のサイトでデータベースへの書き込み権限を必要とします。
4. 同一構成を採用することで、Geoサイト間の同等性を最大限に保つことができます。

オブジェクトストレージメタデータへのリバート

メタデータインポートが完了した後、レジストリをオブジェクトストレージメタデータを使用するようにリバートできます。

オブジェクトストレージメタデータにリバートするには、以下を実行します:

1. 移行前に作成されたバックアップを復元します。

2. 次の設定を/etc/gitlab/gitlab.rbファイルに追加します:

   registry['database'] = {
     'enabled' => false,
   }

3. ファイルを保存し、GitLabを再設定します。

トラブルシューティング

エラーとトラブルシューティングの解決策と回避策を確認するには、コンテナレジストリメタデータデータベースのトラブルシューティングを参照してください。