コンテナレジストリのメタデータデータベースのトラブルシューティング

エラー: there are pending database migrations

レジストリが更新され、保留中のスキーマの移行がある場合、レジストリは次のエラーメッセージで起動に失敗します:

FATA[0000] configuring application: there are pending database migrations, use the 'registry database migrate' CLI command to check and apply them

この問題を解決するには、データベースの移行を適用する手順に従ってください。

バージョン18.3より前は、バージョンをアップグレードするたびに、データベースの移行を手動で適用する必要があります。

エラー: offline garbage collection is no longer possible

レジストリがメタデータデータベースを使用しており、オフラインガベージコレクションを実行しようとすると、レジストリは次のエラーメッセージで失敗します:

ERRO[0000] this filesystem is managed by the metadata database, and offline garbage collection is no longer possible, if you are not using the database anymore, remove the file at the lock_path in this log message lock_path=/docker/registry/lockfiles/database-in-use

次のいずれかの条件を満たす必要があります。

• オフラインガベージコレクションの使用を停止します。
• メタデータデータベースを使用しなくなった場合は、エラーメッセージに表示されているlock_pathにある、指定されたロックファイルを削除します。たとえば、/docker/registry/lockfiles/database-in-useファイルを削除します。

エラー: cannot execute <STATEMENT> in a read-only transaction

レジストリは、次のエラーメッセージでデータベースの移行の適用に失敗する可能性があります:

err="ERROR: cannot execute CREATE TABLE in a read-only transaction (SQLSTATE 25006)"

また、オンラインガベージコレクションを実行しようとすると、レジストリが次のエラーメッセージで失敗する可能性があります:

error="processing task: fetching next GC blob task: scanning GC blob task: ERROR: cannot execute SELECT FOR UPDATE in a read-only transaction (SQLSTATE 25006)"

読み取り専用トランザクションが無効になっていることを確認するには、PostgreSQLコンソールでdefault_transaction_read_onlyとtransaction_read_onlyの値をチェックする必要があります。下記は例です:

# SHOW default_transaction_read_only;
 default_transaction_read_only
 -------------------------------
 on
(1 row)

# SHOW transaction_read_only;
 transaction_read_only
 -----------------------
 on
(1 row)

これらの値のいずれかがonに設定されている場合は、無効にする必要があります:

1. postgresql.confを編集して、次の値を設定します:

   default_transaction_read_only=off

2. これらの設定を適用するには、Postgresサーバーを再起動します。

3. 該当する場合は、データベースの移行の適用を再度試します。

4. レジストリsudo gitlab-ctl restart registryを再起動します。

エラー: cannot import all repositories while the tags table has entries

既存のレジストリメタデータのインポートを実行しようとして、次のエラーが発生する場合があります:

ERRO[0000] cannot import all repositories while the tags table has entries, you must truncate the table manually before retrying,
see https://docs.gitlab.com/administration/packages/container_registry_metadata_database/#troubleshooting
common_blobs=true dry_run=false error="tags table is not empty"

このエラーは、レジストリデータベースのtagsテーブルに既存のエントリがあるときに出ます。エントリは、次の場合に発生する可能性があります:

• ワンステップインポートを試みて、エラーが発生した場合。
• 3ステップインポートプロセスを試みて、エラーが発生した場合。
• インポートプロセスを意図的に停止した場合。
• 以前のいずれかの操作の後で、インポートを再度実行しようとした場合。
• 誤った設定ファイルに対してインポートを実行した場合。

この問題を解決するには、タグテーブル内の既存のエントリを削除する必要があります。PostgreSQLインスタンスで、テーブルを手動で切り捨てる必要があります:

1. /etc/gitlab/gitlab.rbを編集し、メタデータデータベースが無効になっていることを確認します:

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

2. PostgreSQLクライアントを使用して、レジストリデータベースに接続します。

3. tagsテーブルを切り捨てて、既存のエントリをすべて削除します:

   TRUNCATE TABLE tags RESTART IDENTITY CASCADE;

4. tagsテーブルを切り捨てた後、インポートプロセスを再度実行してみてください。

エラー: database-in-use lockfile exists

既存のレジストリメタデータのインポートを実行しようとして、次のエラーが発生する場合があります:

|  [0s] step two: import tags failed to import metadata: importing all repositories: 1 error occurred:
    * could not restore lockfiles: database-in-use lockfile exists

このエラーは、以前にレジストリをインポートし、すべてのリポジトリデータ（ステップ2）のインポートを完了し、database-in-useがレジストリファイルシステムに存在することを意味します。この問題が発生した場合は、インポーターを再度実行しないでください。

続行する必要がある場合は、database-in-useロックファイルをファイルシステムから手動で削除する必要があります。ファイルは/path/to/rootdirectory/docker/registry/lockfiles/database-in-useにあります。

エラー: pre importing all repositories: AccessDenied:

既存のレジストリのインポートを実行し、ストレージバックエンドとしてAWS S3を使用している場合、AccessDeniedエラーが発生する可能性があります:

/opt/gitlab/embedded/bin/registry database import --step-one /var/opt/gitlab/registry/config.yml
  [0s] step one: import manifests
  [0s] step one: import manifests failed to import metadata: pre importing all repositories: AccessDenied: Access Denied

コマンドを実行するユーザーに正しいスコープの権限があることを確認してください。

メタデータ管理の問題が原因でレジストリが起動に失敗しました

レジストリは、次のいずれかのエラーで起動に失敗する可能性があります:

エラー: registry filesystem metadata in use, please import data before enabling the database

このエラーは、設定registry['database'] = { 'enabled' => true}でデータベースが有効になっているにもかかわらず、メタデータデータベースに既存のレジストリメタデータをインポートしていない場合に発生します。

エラー: registry metadata database in use, please enable the database

このエラーは、メタデータデータベースへの既存のレジストリメタデータのインポートが完了したにもかかわらず、設定でデータベースを有効にしていない場合に発生します。

ロックファイルのチェックまたは作成に関する問題

次のいずれかのエラーが発生した場合:

• could not check if filesystem metadata is locked
• could not check if database metadata is locked
• failed to mark filesystem for database only usage
• failed to mark filesystem only usage

レジストリは、設定されたrootdirectoryにアクセスできません。以前に動作していたレジストリがある場合は、このエラーが発生する可能性は低いです。設定ミスの問題がないかエラーログをレビューしてください。

タグを削除した後もストレージ使用量が減少しない

デフォルトでは、オンラインガベージコレクターは、関連付けられていたすべてのタグが削除されてから48時間後に、参照されていないレイヤーの削除を開始します。この遅延は、レイヤーがイメージやタグに関連付けられる前にレジストリへプッシュされるため、ガベージコレクターが長時間実行中または中断されたイメージのプッシュ処理に影響を与えないようにするためのものです。

エラー: permission denied for schema public (SQLSTATE 42501)

レジストリの移行またはGitLabのアップグレード中に、次のいずれかのエラーが発生する可能性があります:

• ERROR: permission denied for schema public (SQLSTATE 42501)
• ERROR: relation "public.blobs" does not exist (SQLSTATE 42P01)

この種のエラーは、PostgreSQL 15以降での仕様変更が原因です。セキュリティ上の理由から、デフォルトでpublicスキーマに対するCREATE権限が削除されました。そのため、PostgreSQL 15以降では、デフォルトではデータベースのオーナーのみがpublicスキーマ内にオブジェクトを作成できます。

エラーを解決するには、次のコマンドを実行して、レジストリデータベースのオーナー特権をレジストリユーザーに付与します:

ALTER DATABASE <registry_database_name> OWNER TO <registry_user>;

これにより、レジストリユーザーは、テーブルを作成し、移行を正常に実行するために必要な許可が付与されます。

エラー: database-in-use and filesystem-in-use lockfiles present

このエラーは、設定されたレジストリストレージにfilesystem-in-useとdatabase-in-useのロックファイルの両方が存在し、あいまいなレジストリ状態を示している場合に発生します。

このエラーを解決するには、レジストリがメタデータデータベースと従来のメタデータストレージのどちらを使用するように設計されているかを判断する必要があります。

レジストリがメタデータデータベースを使用するように設計されている可能性が高いのは、次の場合です:

• 以前にインポート処理のいずれかを実行したことがある。
• レジストリの設定がレジストリが有効になっていることを示している。

レジストリが有効になっているかどうかを確認するには、/etc/gitlab/gitlab.rbにあるファイルを確認してください:

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

レジストリがデータベースを使用するように設計されていることを確認したら、/docker/registry/lockfiles/filesystem-in-useに存在する、設定されたレジストリストレージにあるfilesystem-in-useロックファイルを削除します。

または、上記のシナリオが当てはまらず、レジストリが従来のメタデータストレージを使用するように設計されている場合は、/docker/registry/lockfiles/database-in-useにあるdatabase-in-useロックファイルを削除します。

最後に、コンテナレジストリの機能フラグREGISTRY_FF_ENFORCE_LOCKFILESをfalseに設定することで、ロックファイルのチェックを無効にできます。ただし、このエラーはレジストリデータの整合性を確保するためのものです。使用しているメタデータストレージの種類を確認することをおすすめします。REGISTRY_FF_ENFORCE_LOCKFILESは非推奨となっており、GitLab 18.10で削除が予定されています。詳細については、コンテナレジストリの機能フラグを参照してください。