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

メタデータデータベースは、オンラインガベージコレクションなど、多くの新しいレジストリ機能を提供し、多くのレジストリ操作の効率性を高めます。

既存のレジストリがある場合は、メタデータデータベースに移行できます。

データベースが有効になっている機能の一部は、GitLab.comでのみ有効になっており、レジストリデータベースの自動データベースプロビジョニングは利用できません。コンテナレジストリデータベースに関連する機能のステータスについては、管理ドキュメントの機能サポートセクションを確認してください。

外部メタデータデータベースを作成

本番環境では、外部メタデータデータベースを作成する必要があります。

前提要件:

• 外部PostgreSQLサーバーをセットアップします。

外部PostgreSQLサーバーをセットアップした後:

1. メタデータデータベースのシークレットを作成します:

   kubectl create secret generic RELEASE_NAME-registry-database-password --from-literal=password=<your_registry_password>

2. データベースサーバーにログインします。

3. 次のSQLコマンドを使用して、ユーザー名とデータベースを作成します:

   -- Create the registry user
   CREATE USER registry WITH PASSWORD '<your_registry_password>';
   
   -- Create the registry database
   CREATE DATABASE registry OWNER registry;

4. クラウドマネージドサービスの場合は、必要に応じて追加のロールを付与します:

   Amazon RDS

   GRANT rds_superuser TO registry;

   Azure database

   GRANT azure_pg_admin TO registry;

   Google Cloud SQL

   GRANT cloudsqlsuperuser TO registry;

組み込みメタデータデータベースを作成

データベースを自動的に作成

前提要件:

• Helmチャート9.3バージョン以降。

GitLabチャートのインストール時にpostgresql.install=trueを設定する新しいインストールでは、レジストリデータベース、ユーザー名、および共有シークレットRELEASE-registry-database-passwordが自動的に作成されます。

この自動プロビジョニング:

• 専用のregistryデータベースを作成します。
• 適切な権限を持つregistryユーザー名をセットアップします。
• データベースパスワードを含むRELEASE-registry-database-passwordシークレットを生成します。
• 必要なデータベーススキーマと権限を設定します。

自動データベース作成を使用すると、手動データベース作成手順をスキップして、すぐにメタデータデータベースを有効にすることができます。

データベースを手動で作成

組み込みPostgreSQLサーバーを使用してメタデータデータベースを手動で作成するには:

1. データベースパスワードでシークレットを作成します:

   kubectl create secret generic RELEASE_NAME-registry-database-password --from-literal=password=<your_registry_password>

2. データベースインスタンスにログインします:

   kubectl exec -it $(kubectl get pods -l app.kubernetes.io/name=postgresql -o custom-columns=NAME:.metadata.name --no-headers) -- bash

   PGPASSWORD=${POSTGRES_POSTGRES_PASSWORD} psql -U postgres -d template1

3. データベースユーザーを作成します:

   CREATE ROLE registry WITH LOGIN;

4. データベースユーザー名のパスワードを設定します。

   1. パスワードをフェッチします:

      kubectl get secret RELEASE_NAME-registry-database-password -o jsonpath="{.data.password}" | base64 --decode

   2. psqlプロンプトでパスワードを設定します:

      \password registry

5. データベースを作成します:

   CREATE DATABASE registry WITH OWNER registry;

6. PostgreSQLコマンドラインから、次にexitを使用してコンテナから安全に終了します:

   template1=# exit
   ...@gitlab-postgresql-0/$ exit

メタデータデータベースを有効にする

データベースを作成したら、有効にします。既存のコンテナレジストリを移行する場合は、追加の手順が必要です。

前提要件

前提要件:

• GitLab 17.3以降。
• レジストリポッドからアクセス可能な、必要なバージョンのPostgreSQLのデプロイ。
• KubernetesクラスタリングとHelmデプロイにローカルでアクセスします。
• レジストリポッドへのSSHアクセス。

レジストリ管理ガイドの開始する前にのセクションも読んでください。

新しいレジストリを有効にする

新しいコンテナレジストリのデータベースを有効にするには:

1. リリースの現在のHelm値を取得し、ファイルに保存します。たとえば、gitlabという名前のリリースと、values.ymlという名前のファイルの場合:

   helm get values gitlab > values.yml

2. values.ymlファイルに次の行を追加します:

   registry:
     enabled: true
     database:
       enabled: true
       name: registry  # must match the database name you created above
       user: registry  # must match the database username you created above
       password:
         secret: gitlab-registry-database-password # must match the secret name
         key: password  # must match the secret key to read the password from
       sslmode: verify-full
       # these settings are inherited from `global.psql.ssl`
       ssl:
         secret: gitlab-registry-postgresql-ssl # you will need to create this secret manually
         clientKey: client-key.pem
         clientCertificate: client-cert.pem
         serverCA: server-ca.pem
       migrations:
         enabled: true  # this option will execute the schema migration as part of the registry deployment

3. オプション。スキーマ移行が正しく適用されていることを確認します。次のいずれかの方法があります:

   • 移行ジョブのログ出力を確認します。例:

     kubectl logs jobs/gitlab-registry-migrations-1
     ...
     OK: applied 154 migrations in 13.752s

   • または、Postgresデータベースに接続し、schema_migrationsテーブルに対してクエリを実行します:

     SELECT * FROM schema_migrations;

     applied_at列のタイムスタンプがすべての行に入力されていることを確認します。

レジストリは、メタデータデータベースを使用する準備ができました!

既存のレジストリを有効にしてインポートする

既存のコンテナレジストリデータを1つのステップまたは3つのステップでインポートできます。いくつかの要因が移行の期間に影響を与えます:

• 既存のレジストリデータのサイズ。
• PostgresSQLインスタンスの仕様。
• クラスタリングで実行されているレジストリポッドの数。
• レジストリ、PostgresSQL、および設定されたオブジェクトストレージ間のネットワークレイテンシー。

1ステップまたは3ステップのインポートを試みる前に、リリースの現在のHelm値を取得し、ファイルに保存します。たとえば、gitlabという名前のリリースと、values.ymlという名前のファイルの場合:

helm get values gitlab > values.yml

1つのステップでインポートする

1ステップのインポートを実行する場合は、以下に注意してください:

• レジストリは、インポート中はread-only読み取り専用モードのままにする必要があります。
• インポートが実行されているポッドが終了した場合、プロセスを完全に再起動する必要があります。このプロセスを改善する作業は、イシュー5293で追跡されています。

既存のコンテナレジストリを1つのステップでメタデータデータベースにインポートするには:

1. values.ymlファイルのregistry:セクションを見つけて、databaseセクションを追加します。以下を設定します:

   • database.configureをtrueに設定します。
   • database.enabledをfalseに設定します。
   • maintenance.readonly.enabledをtrueに設定します。
   • migrations.enabledをtrueに設定します。
   registry:
     enabled: true
     maintenance:
       readonly:
         enabled: true  # must remain set to true while the migration is executed
     database:
       configure: true  # must be true for the migration step
       enabled: false  # must be false!
       name: registry  # must match the database name you created above
       user: registry  # must match the database username you created above
       password:
         secret: gitlab-registry-database-password  # must match the secret name
         key: password  # must match the secret key to read the password from
       sslmode: verify-full  # SSL connection mode. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION for more options.
       ssl:
         secret: gitlab-registry-postgresql-ssl  # you will need to create this secret manually
         clientKey: client-key.pem
         clientCertificate: client-cert.pem
         serverCA: server-ca.pem
       migrations:
         enabled: true  # this option will execute the schema migration as part of the registry deployment

2. Helmインストールをアップグレードして、デプロイの変更を適用します:

   helm upgrade gitlab gitlab/gitlab -f values.yml

3. SSH経由でレジストリポッドの1つに接続します（たとえば、gitlab-registry-5ddcd9f486-bvb57という名前のポッドの場合）:

   kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash

4. ホームディレクトリに変更してから、次のコマンドを実行します:

   cd ~
   /usr/bin/registry database import /etc/docker/registry/config.yml

5. コマンドが正常に完了すると、すべてのイメージが完全にインポートされます。データベースを有効にして、設定で読み取り専用モードをオフにすることができます:

   registry:
     enabled: true
     maintenance:
       readonly:
         enabled: false
     database:
       configure: true  # once database.enabled is set to true, this option can be removed
       enabled: true
       name: registry
       user: registry
       password:
         secret: gitlab-registry-database-password
         key: password
       migrations:
         enabled: true

6. Helmインストールをアップグレードして、デプロイの変更を適用します:

   helm upgrade gitlab gitlab/gitlab -f values.yml

メタデータデータベースをすべての操作に使用できるようになりました!

3つのステップでインポートする

既存のコンテナレジストリデータを3つの個別のステップでメタデータデータベースにインポートできます。これは、次の場合に推奨されます:

• レジストリに大量のデータが含まれている。
• 移行中のダウンタイムを最小限に抑える必要がある。

3つのステップでインポートするには、次の操作を行う必要があります:

1. リポジトリの事前インポート
2. すべてのリポジトリデータをインポートする
3. 共通blobをインポートする

ステップ1.リポジトリを事前にインポートする

大規模なインスタンスの場合、このプロセスは、レジストリのサイズに応じて、完了までに数時間または数日かかる場合があります。このプロセス中にレジストリを引き続き使用できます。

1. values.ymlファイルのregistry:セクションを見つけて、databaseセクションを追加します。以下を設定します:

   • database.configureをtrueに設定します。
   • database.enabledをfalseに設定します。
   • migrations.enabledをtrueに設定します。
   registry:
     enabled: true
     database:
       configure: true
       enabled: false  # must be false!
       name: registry  # must match the database name you created above
       user: registry  # must match the database username you created above
       password:
         secret: gitlab-registry-database-password  # must match the secret name
         key: password  # must match the secret key to read the password from
       sslmode: verify-full  # SSL connection mode. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION for more options.
       ssl:
         secret: gitlab-registry-postgresql-ssl  # you will need to create this secret manually
         clientKey: client-key.pem
         clientCertificate: client-cert.pem
         serverCA: server-ca.pem
       migrations:
         enabled: true  # this option will execute the schema migration as part of the registry deployment

2. ファイルを保存し、Helmインストールをアップグレードして、デプロイの変更を適用します:

   helm upgrade gitlab gitlab/gitlab -f values.yml

3. SSHを使用してレジストリポッドの1つに接続します。たとえば、gitlab-registry-5ddcd9f486-bvb57という名前のポッドの場合:

   kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash

4. ホームディレクトリに変更してから、次のコマンドを実行します:

   cd ~
   /usr/bin/registry database import --step-one /etc/docker/registry/config.yml

registry import completeが表示されると、最初の手順は完了です。

ステップ2.すべてのリポジトリデータをインポートする

このステップでは、レジストリをread-only読み取り専用モードに設定する必要があります。このプロセス中にダウンタイムに十分な時間を確保してください。

1. values.ymlファイルで、レジストリをread-only読み取り専用モードに設定します:

   registry:
     enabled: true
     maintenance:
       readonly:
         enabled: true   # must be true!
     database:
       configure: true
       enabled: false  # must be false!
       name: registry  # must match the database name you created above
       user: registry  # must match the database username you created above
       password:
         secret: gitlab-registry-database-password  # must match the secret name
         key: password  # must match the secret key to read the password from
       sslmode: verify-full  # SSL connection mode. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION for more options.
       ssl:
         secret: gitlab-registry-postgresql-ssl  # you will need to create this secret manually
         clientKey: client-key.pem
         clientCertificate: client-cert.pem
         serverCA: server-ca.pem
       migrations:
         enabled: true  # this option will execute the schema migration as part of the registry deployment

2. ファイルを保存し、Helmインストールをアップグレードして、デプロイの変更を適用します:

   helm upgrade gitlab gitlab/gitlab -f values.yml

3. SSHを使用してレジストリポッドの1つに接続します。たとえば、gitlab-registry-5ddcd9f486-bvb57という名前のポッドの場合:

   kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash

4. ホームディレクトリに変更してから、次のコマンドを実行します:

   cd ~
   /usr/bin/registry database import --step-two /etc/docker/registry/config.yml

5. コマンドが正常に完了すると、すべてのイメージが完全にインポートされます。データベースを有効にして、設定で読み取り専用モードをオフにすることができます:

   registry:
     enabled: true
     maintenance:        # this section can be removed
       readonly:
         enabled: false
     database:
       configure: true  # once database.enabled is set to true, this option can be removed
       enabled: true   # must be true!
       name: registry  # must match the database name you created above
       user: registry  # must match the database username you created above
       password:
         secret: gitlab-registry-database-password  # must match the secret name
         key: password  # must match the secret key to read the password from
       sslmode: verify-full  # SSL connection mode. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION for more options.
       ssl:
         secret: gitlab-registry-postgresql-ssl  # you will need to create this secret manually
         clientKey: client-key.pem
         clientCertificate: client-cert.pem
         serverCA: server-ca.pem
       migrations:
         enabled: true  # this option will execute the schema migration as part of the registry deployment

6. ファイルを保存し、Helmインストールをアップグレードして、デプロイの変更を適用します:

   helm upgrade gitlab gitlab/gitlab -f values.yml

メタデータデータベースをすべての操作に使用できるようになりました!

ステップ3.共通blobをインポートする

レジストリは、メタデータにデータベースを完全に使用するようになりましたが、まだ潜在的に未使用のレイヤーblobへのアクセス権がありません。

プロセスを完了するには、移行の最後の手順を実行します:

cd ~
/usr/bin/registry database import --step-three /etc/docker/registry/config.yml

コマンドが正常に完了すると、レジストリはデータベースに完全に移行されました!

データベースの移行

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

• 通常のスキーマの移行: 新しいアプリケーションコードをデプロイする前に実行する必要があるデータベース構造への変更。これらは、デプロイの遅延を回避するために高速である必要があります。

• デプロイ後の移行: アプリケーションの実行中に実行できるデータベース構造への変更。大規模なテーブルにインデックスを作成するなどのより長い操作に使用され、起動の遅延と拡張されたアップグレードのダウンタイムを回避します。

データベース移行を適用する

デフォルトでは、database.migrations.enabledがtrueに設定されている場合、レジストリチャートは、通常のスキーマとデプロイ後の移行の両方を自動的に適用します。

アップグレード中のダウンタイムを削減するために、デプロイ後の移行をスキップし、アプリケーションの起動後に手動で適用できます:

1. レジストリデプロイのExtraEnvを使用して、SKIP_POST_DEPLOYMENT_MIGRATIONS環境変数をtrueに設定します:

   registry:
     extraEnv:
       SKIP_POST_DEPLOYMENT_MIGRATIONS: true

2. アップグレード後、レジストリポッドに接続する。

3. 保留中のデプロイ後の移行を適用します:

   registry database migrate up /etc/docker/registry/config.yml

トラブルシューティング

エラー: panic: interface conversion: interface {} is nil, not bool

既存のレジストリをインポートすると、このエラーが表示されることがあります:

panic: interface conversion: interface {} is nil, not bool

これは、レジストリバージョンv4.15.2-gitlabおよびGitLab 17.9以降で修正された既知のイシューです。

このイシューを回避するには、レジストリバージョンをアップグレードします:

1. values.ymlファイルで、レジストリイメージタグ付けを設定します:

   registry:
     image:
       tag: v4.15.2-gitlab

2. Helmインストールをアップグレードします:

   helm upgrade gitlab -f values.yml

または、レジストリの設定を手動で更新することもできます:

• /etc/docker/registry/config.ymlで、ストレージプロバイダーのparallelwalkをfalseに設定します。例: S3を使用する場合:

  storage:
    s3:
      parallelwalk: false