오류: 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 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단계 가져오기 프로세스를 시도했다가 오류가 발생한 경우.
• 가져오기 프로세스를 의도적으로 중단한 경우.
• 이전 작업 후 가져오기를 다시 실행하려고 한 경우.
• 잘못된 구성 파일에 대해 가져오기를 실행한 경우.

이 문제를 해결하려면 tags 테이블의 기존 항목을 삭제해야 합니다. 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

명령을 실행하는 사용자에게 올바른 권한 범위가 있는지 확인하십시오.

오류: convert field 8 failed: invalid hex format#

기존 레지스트리 데이터를 메타데이터 데이터베이스로 가져올 때, 매니페스트를 읽는 동안 가져오기가 실패할 수 있습니다:

ERRO[0000] pre importing tagged manifests common_blobs=false dry_run=false error="finding tagged manifests in database: scanning manifest: convert field 8 failed: invalid hex format"

이 오류는 PostgreSQL 서버 또는 레지스트리의 데이터베이스 역할(role)이 bytea_output = escape로 구성되어 있을 때 발생합니다. 레지스트리는 일부 바이너리 칼럼을 텍스트로 읽으며 기본 16진수 형식을 기대합니다.

레지스트리가 사용하는 것과 동일한 연결 경로를 통해, 예를 들어 PgBouncer를 사용하는 경우 이를 통해 값을 확인합니다:

SELECT current_setting('bytea_output');

오류를 해결하려면 레지스트리 데이터베이스의 출력 형식을 hex로 설정합니다:

ALTER DATABASE <registry_database> SET bytea_output = 'hex';

그런 다음 레지스트리를 재시작하거나 새 연결을 열어 레지스트리를 다시 연결한 후 가져오기를 재시도합니다. 역할 수준(role-level) 설정이 데이터베이스 기본값을 재정의하므로, 역할이 bytea_output을 설정하는 경우 해당 역할에도 설정합니다:

ALTER ROLE <registry_user> SET bytea_output = 'hex';

메타데이터 관리 문제로 인한 레지스트리 시작 실패#

다음 오류 중 하나와 함께 레지스트리가 시작에 실패할 수 있습니다:

오류: 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)

이러한 유형의 오류는 보안 이유로 공개 스키마에 대한 기본 CREATE 권한을 제거한 PostgreSQL 15+의 변경으로 인한 것입니다. 기본적으로 PostgreSQL 15+에서는 데이터베이스 소유자만 공개 스키마에 객체를 생성할 수 있습니다.

오류를 해결하려면 다음 명령을 실행하여 레지스트리 사용자에게 레지스트리 데이터베이스의 소유자 권한을 부여합니다:

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 잠금 파일을 삭제합니다.

GitLab 18.8 및 18.9의 경우, REGISTRY_FF_ENFORCE_LOCKFILES 컨테이너 레지스트리 기능 플래그를 false로 설정하여 잠금 파일 검사를 비활성화할 수 있습니다. 이 설정으로 검사가 비활성화되지만, 이 오류는 레지스트리 데이터의 무결성을 보장하기 위한 것이므로 사용 중인 메타데이터 스토리지를 확인하는 것이 좋습니다. REGISTRY_FF_ENFORCE_LOCKFILES 기능 플래그는 GitLab 18.10에서 제거되었습니다. 자세한 내용은 컨테이너 레지스트리 기능 플래그를 참조하십시오.