• 알려진 제한 사항
• 메타데이터 데이터베이스 기능 지원
• Linux 패키지 설치를 위한 메타데이터 데이터베이스 활성화
  • 시작하기 전에
  • 새 설치
  • 기존 레지스트리
    • 일 단계 마이그레이션
    • 3단계 마이그레이션
      • 저장소 사전 가져오기 (1단계)
      • 모든 저장소 데이터 가져오기 (2단계)
      • 나머지 데이터 가져오기 (3단계)
    • 마이그레이션 후
• 스키마 마이그레이션 관리
  • 스키마 마이그레이션 적용
  • 스키마 마이그레이션 취소
• 온라인 가비지 컬렉션 모니터링
  • 데이터베이스 성능 모니터링
  • 메트릭 추적
  • 대기열 모니터링
  • 블롭 간격 조정
  • 데이터 일관성 검증
  • 정리 정책 검토
• 메타데이터 데이터베이스와 백업
• 레지스트리 다운그레이드
• 문제 해결
  • 오류: 미결 데이터베이스 마이그레이션이 있습니다
  • 오류: 오프라인 가비지 수집이 더 이상 불가능합니다
  • 오류: 읽기 전용 거래에서 <STATEMENT>를 실행할 수 없습니다
  • 오류: 모든 리포지토리를 가져올 수 없습니다. 태그 테이블에 항목이 있습니다.
  • 오류: database-in-use lockfile exists
  • 메타데이터 관리 문제로 인해 레지스트리가 시작되지 않음
    • 오류: 레지스트리 파일 시스템 메타데이터가 사용 중입니다. 데이터베이스를 활성화하기 전에 데이터를 가져와야 합니다.
    • 오류: 레지스트리 메타데이터 데이터베이스가 사용 중입니다. 데이터베이스를 활성화해야 합니다.
    • 잠금 파일을 확인하거나 생성하는 데 문제가 발생했습니다

컨테이너 레지스트리 메타데이터 데이터베이스

Offering: Self-managed

• GitLab 16.4에서 자가 관리 GitLab 인스턴스를 위한 베타 기능으로 소개됨.
• GitLab 17.3에서 일반 제공됨.

메타데이터 데이터베이스는 온라인 가비지 수집을 포함하여 많은 새로운 레지스트리 기능을 가능하게 하고, 레지스트리 작업의 효율성을 증가시킵니다.

레지스트리 메타데이터 데이터베이스 기능의 자가 관리 릴리스 작업은 에픽 5521로 추적됩니다.

기본적으로, 컨테이너 레지스트리는 컨테이너 이미지와 관련된 메타데이터를 영속성 저장하기 위해 객체 저장소를 사용합니다. 메타데이터를 저장하는 이 방법은 태그 나열 시와 같이 여러 이미지에 걸쳐 데이터를 효율적으로 접근하는 방식을 제한합니다.

이 데이터를 데이터베이스에 저장함으로써, 온라인 가비지 수집과 같은 많은 새로운 기능을 사용할 수 있습니다. 이 기능은 가동 중지 시간 없이 자동으로 오래된 데이터를 제거합니다.

이 데이터베이스는 이미 레지스트리에서 사용 중인 객체 저장소와 함께 작동하지만, 객체 저장소를 대체하지는 않습니다. 메타데이터 데이터베이스로 마이그레이션한 후에도 반드시 객체 저장소 솔루션을 유지해야 합니다.

Helm 차트 설치에 대한 자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스 관리하기 에서 확인하세요.

알려진 제한 사항

• 온라인 마이그레이션을 지원하지 않습니다.
• Geo 지원이 확인되지 않았습니다.
• 버전을 업그레이드할 때 레지스트리 데이터베이스 마이그레이션은 수동으로 실행해야 합니다.
• 다중 노드 Omnibus GitLab 환경에서 업그레이드 중 레지스트리의 제로 다운타임을 보장하지 않습니다.

메타데이터 데이터베이스 기능 지원

기존 레지스트리를 메타데이터 데이터베이스로 마이그레이션할 수 있으며, 온라인 가비지 수집을 사용할 수 있습니다.

일부 데이터베이스 기반 기능은 GitLab.com에서만 활성화되며 레지스트리 데이터베이스를 위한 자동 데이터베이스 프로비저닝은 제공되지 않습니다. 컨테이너 레지스트리 데이터베이스와 관련된 기능의 상태는 피드백 문제에서 기능 지원 표를 확인하세요.

Linux 패키지 설치를 위한 메타데이터 데이터베이스 활성화

사전 요구 사항:

• GitLab 17.3 이상.
• PostgreSQL 데이터베이스 버전 12 이상. 레지스트리 노드에서 접근 가능해야 합니다.

상황에 맞는 지침을 따르세요:

• 새 설치 또는 처음으로 컨테이너 레지스트리 활성화하기.
• 기존 컨테이너 이미지를 메타데이터 데이터베이스로 마이그레이션하기:
  • 1단계 마이그레이션. 상대적으로 작은 레지스트리나 가동 중지 시간을 피할 필요가 없는 경우에만 추천됩니다.
  • 3단계 마이그레이션. 더 큰 컨테이너 레지스트리에 권장됩니다.

시작하기 전에

• 데이터베이스를 활성화한 후에는 계속 사용해야 합니다. 데이터베이스는 이제 레지스트리 메타데이터의 출처이며, 이 시점 이후에 비활성화하면 데이터베이스가 활성화된 동안 레지스트리에 작성된 모든 이미지에 대한 가시성이 사라집니다.

• 가져오기 단계를 완료한 후에는 오프라인 가비지 수집을 절대 실행하지 마십시오. 해당 명령은 메타데이터 데이터베이스를 사용하는 레지스트리와 호환되지 않으며, 데이터를 삭제합니다.

• 오프라인 가비지 수집을 자동화하지 않았는지 확인하세요.

• 먼저 레지스트리 저장소 줄이기를 수행하여 프로세스를 가속화할 수 있습니다.

• 가능하다면 컨테이너 레지스트리 데이터를 백업하세요.

새 설치

데이터베이스를 활성화하려면:

1. /etc/gitlab/gitlab.rb를 편집하여 데이터베이스 연결 세부정보를 추가하되, 메타데이터 데이터베이스를 비활성화된 상태로 시작합니다:

   registry['database'] = {
     'enabled' => false,
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # 추가 정보는 PostgreSQL 문서를 참조하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   

2. 파일을 저장하고 GitLab 재구성하기를 실행합니다.

3. 스키마 마이그레이션 적용하기를 실행합니다.

4. /etc/gitlab/gitlab.rb를 편집하여 데이터베이스를 활성화하고 enabled를 true로 설정합니다:

   registry['database'] = {
     'enabled' => true,
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # 추가 정보는 PostgreSQL 문서를 참조하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   

5. 파일을 저장하고 GitLab 재구성하기를 실행합니다.

기존 레지스트리

기존의 컨테이너 레지스트리 데이터를 한 단계 또는 세 단계로 마이그레이션할 수 있습니다.

마이그레이션 기간에 영향을 미치는 몇 가지 요인:

• 기존 레지스트리 데이터의 크기.
• PostgreSQL 인스턴스의 사양.
• 실행 중인 레지스트리 인스턴스의 수.
• 레지스트리, PostgreSQL 및 구성된 객체 저장소 간의 네트워크 대기 시간.

참고: 마이그레이션은 태그가 지정된 이미지에만 적용됩니다. 태그가 없는 이미지와 참조되지 않는 매니페스트, 그리고 이들에 의해 독점적으로 참조되는 레이어는 남겨지고 접근할 수 없게 됩니다. 태그가 없는 이미지는 GitLab UI나 API를 통해 결코 보이지 않지만, “어중간한” 상태가 되어 백엔드에 남아 있을 수 있습니다. 새로운 레지스트리로 마이그레이션한 후, 모든 이미지는 기본적으로 24시간 이상 남아 있는 태그가 없는 매니페스트와 레이어를 삭제하는 지속적인 온라인 가비지 수집의 대상이 됩니다.

레지스트리 설치에 따라 1단계 또는 3단계 방법 중 하나를 선택하세요.

일 단계 마이그레이션

경고: 마이그레이션 중 레지스트리는 종료되거나 읽기 전용 모드여야 합니다.

마이그레이션 중 레지스트리에 쓰기가 필요 없고 레지스트리에 상대적으로 적은 양의 데이터가 포함된 경우에만 이 방법을 선택하세요.

1. /etc/gitlab/gitlab.rb 파일에 database 섹션을 추가하되, 메타데이터 데이터베이스를 비활성화된 상태로 시작합니다:

   registry['database'] = {
     'enabled' => false, # 반드시 false여야 합니다!
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # 추가 정보는 PostgreSQL 문서를 참조하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   

2. 레지스트리가 읽기 전용 모드로 설정되어 있는지 확인합니다.

   /etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다.

   예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우, 다음과 같이 구성할 수 있습니다:

   ## 객체 저장소 - 컨테이너 레지스트리
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => true # 반드시 true로 설정해야 합니다.
       }
     }
   }
   

3. 파일을 저장하고 GitLab 재구성하기를 실행합니다.

4. 이전에 하지 않았다면 스키마 마이그레이션 적용하기를 실행합니다.

5. 다음 명령을 실행합니다:

   sudo gitlab-ctl registry-database import
   

6. 명령이 성공적으로 완료되면, 레지스트리가 이제 완전히 가져오기된 상태입니다.

   데이터베이스를 활성화하고 구성에서 읽기 전용 모드를 끄고 레지스트리 서비스를 시작할 수 있습니다:

   registry['database'] = {
     'enabled' => true, # 지금은 활성화되어야 합니다!
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # 추가 정보는 PostgreSQL 문서를 참조하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   
   ## 객체 저장소 - 컨테이너 레지스트리
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => false
       }
     }
   }
   

7. 파일을 저장하고 GitLab 재구성하기를 실행합니다.

이제 모든 작업에 대해 메타데이터 데이터베이스를 사용할 수 있습니다!

3단계 마이그레이션

기존 컨테이너 레지스트리 데이터를 마이그레이션하는 방법에 대한 가이드를 따르세요.

이 절차는 더 큰 데이터 세트에 권장되며, 마이그레이션을 완료하는 동안 다운타임을 최소화하려는 경우에 유용합니다.

주의: 사용자들은 1단계 가져오기가 시간당 2~4TB의 속도로 완료되었다고 보고했습니다.

느린 속도에서는 100TB 이상의 데이터가 있는 레지스트리는 48시간 이상 걸릴 수 있습니다.

저장소 사전 가져오기 (1단계)

더 큰 인스턴스의 경우, 이 명령은 레지스트리의 크기에 따라 몇 시간에서 몇 일이 걸릴 수 있습니다. 1단계가 완료되는 동안 레지스트리를 정상적으로 사용할 수 있습니다.

경고: 마이그레이션을 재시작하는 것은 아직 불가능하므로, 마이그레이션이 완료될 때까지 진행해야 합니다. 만약 작업을 중단해야 하는 경우, 이 단계를 다시 시작해야 합니다.

1. /etc/gitlab/gitlab.rb 파일에 database 섹션을 추가하되, 메타데이터 데이터베이스는 비활성화 상태에서 시작합니다:

   registry['database'] = {
     'enabled' => false, # Must be false!
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # PostgreSQL 문서에서 추가 정보를 확인하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   

2. 파일을 저장하고 GitLab을 재구성하세요.

3. 스키마 마이그레이션을 적용하지 않았다면 진행하세요.

4. 마이그레이션을 시작하려면 첫 번째 단계를 실행하세요:

   sudo gitlab-ctl registry-database import --step-one
   

주의: 다운타임을 줄이기 위해 가능한 한 빨리 다음 단계를 예약해야 합니다.

이상적으로는 1단계가 완료된 후 일주일 이내에 진행되어야 합니다. 1단계와 2단계 사이에 레지스트리에 기록된 새로운 데이터는 2단계가 더 많은 시간을 소모하게 만듭니다.

모든 저장소 데이터 가져오기 (2단계)

이 단계에서는 레지스트리를 종료하거나 read-only 모드로 설정해야 합니다.

2단계가 실행되는 동안 충분한 다운타임 시간을 허용하세요.

1. 레지스트리가 read-only 모드로 설정되었는지 확인하세요.

   /etc/gitlab/gitlab.rb 파일을 수정하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 기반 레지스트리의 경우 구성은 다음과 같을 수 있습니다:

   ## 객체 저장소 - 컨테이너 레지스트리
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => true # 반드시 true로 설정해야 합니다.
       }
     }
   }
   

2. 파일을 저장하고 GitLab을 재구성하세요.

3. 마이그레이션의 2단계를 실행하세요:

   sudo gitlab-ctl registry-database import --step-two
   

4. 명령이 성공적으로 완료되면 모든 이미지가 완전히 가져와진 것입니다.

   이제 데이터베이스를 활성화하고 구성에서 읽기 전용 모드를 끄고 레지스트리 서비스를 시작할 수 있습니다:

   registry['database'] = {
     'enabled' => true, # 반드시 true로 설정해야 합니다!
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # PostgreSQL 문서에서 추가 정보를 확인하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   
   ## 객체 저장소 - 컨테이너 레지스트리
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => { # 이 섹션은 제거할 수 있습니다.
       'readonly' => {
         'enabled' => false
       }
     }
   }
   

5. 파일을 저장하고 GitLab을 재구성하세요.

이제 모든 작업에 메타데이터 데이터베이스를 사용할 수 있습니다!

나머지 데이터 가져오기 (3단계)

레지스트리가 이제 메타데이터에 대한 데이터베이스를 완전히 사용하고 있지만,

아직 사용하지 않는 레이어 블롭에 대한 액세스는 없습니다.

프로세스를 완료하려면 마이그레이션의 마지막 단계를 실행하세요:

sudo gitlab-ctl registry-database import --step-three

해당 명령이 성공적으로 종료된 후, 레지스트리는 이제 데이터베이스로 완전히 마이그레이션되었습니다!

마이그레이션 후

마이그레이션 후 약 48시간 정도 지나야 레지스트리 스토리지가 감소하는 것을 볼 수 있습니다.

이는 온라인 가비지 컬렉션의 정상적이고 예상된 부분으로, 이 지연은 온라인 가비지 컬렉션이 이미지 푸시와 간섭하지 않도록 보장합니다.

온라인 가비지 컬렉션의 진행 상황과 상태를 모니터링하는 방법은 모니터 온라인 가비지 컬렉션 섹션을 확인하세요.

스키마 마이그레이션 관리

컨테이너 레지스트리 메타데이터 데이터베이스의 스키마 마이그레이션을 실행하려면 다음 명령어를 사용하세요.

레지스트리는 활성화되어 있어야 하며, 구성 섹션에는 데이터베이스 섹션이 채워져 있어야 합니다.

스키마 마이그레이션 적용

1. 레지스트리 데이터베이스 스키마 마이그레이션을 실행합니다.

   sudo gitlab-ctl registry-database migrate up
   

2. 레지스트리가 실행 중인 경우 정지해야 합니다. y를 입력하여 확인하고 프로세스가 완료될 때까지 기다리세요.

자세한 내용은 sudo gitlab-ctl registry-database migrate up --help를 실행하세요.

스키마 마이그레이션 취소

문제가 발생한 경우 스키마 마이그레이션을 취소할 수 있지만,

이는 복구할 수 없는 작업입니다.

데이터베이스가 사용 중일 때 새 이미지를 푸시한 경우,

이제 더 이상 접근할 수 없습니다.

1. 레지스트리 데이터베이스 스키마 마이그레이션을 취소합니다:

   sudo gitlab-ctl registry-database migrate down
   

자세한 내용은 sudo gitlab-ctl registry-database migrate down --help를 실행하세요.

온라인 가비지 컬렉션 모니터링

가져오기 프로세스 후 초기 온라인 가비지 컬렉션 실행은 가져온 이미지 수에 따라 지속 시간이 달라집니다. 이 기간 동안 온라인 가비지 컬렉션의 효율성과 상태를 모니터링해야 합니다.

데이터베이스 성능 모니터링

가져오기 완료 후, 데이터베이스는 가비지 컬렉션 대기열이 소모되는

기간 동안 높은 부하를 경험할 것으로 예상됩니다. 이 높은 부하는

대기 중인 작업을 처리하는 온라인 가비지 컬렉터로부터의 개별 데이터베이스 호출이 많기 때문입니다.

정기적으로 PostgreSQL 및 레지스트리 로그에서 오류나 경고를 확인하세요.

레지스트리 로그에서는 component=registry.gc.*로 필터링된 로그에 특별히 주의하세요.

메트릭 추적

Prometheus 및 Grafana와 같은 모니터링 도구를 사용하여 가비지 컬렉션 메트릭을 시각화하고 추적하세요,

registry_gc_* 접두사가 있는 메트릭에 집중하세요.

여기에는 삭제를 위해 표시된 객체 수, 성공적으로 삭제된 객체, 실행 간격 및 지속 시간이 포함됩니다.

Prometheus를 활성화하는 방법은 레지스트리 디버그 서버 활성화하기를 참조하세요.

대기열 모니터링

gc_blob_review_queue 및 gc_manifest_review_queue 테이블의 행 수를 세어 대기열 크기를 확인하세요.

초기에는 대기열이 크기가 클 것으로 예상되며, 행 수는 가져온 블롭 및 매니페스트 수에 비례합니다. 대기열은 시간이 지남에 따라 줄어들어야 하며,

이는 가비지 컬렉션이 작업을 성공적으로 검토하고 있음을 나타냅니다.

SELECT COUNT(*) FROM gc_blob_review_queue;
SELECT COUNT(*) FROM gc_manifest_review_queue;

대기열 크기 해석:

• 줄어드는 대기열: 가비지 컬렉션이 성공적으로 작업을 처리하고 있습니다.
• 거의 제로인 gc_manifest_review_queue: 삭제 가능성 있는 대부분의 이미지가 검토되어 여전히 사용 중이거나 삭제된 것으로 분류되었습니다.

• 연체된 작업: 연체된 GC 작업을 확인하려면 다음 쿼리를 실행하세요:

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

  많은 수의 연체 작업은 문제를 나타냅니다. 대기열 크기가 클 경우 시간이 지남에 따라 줄어들고 연체 작업 수가 거의 제로인 경우에는 걱정하지 않아도 됩니다.

많은 수의 연체 작업은 로그를 긴급히 점검해야 할 신호입니다.

GC 로그에서 블롭이 여전히 사용 중이라는 메시지를 확인하세요. 예를 들어, msg=the blob is not dangling와 같은 메시지는 삭제되지 않을 것임을 의미합니다.

블롭 간격 조정

gc_blob_review_queue의 크기가 크고, 가비지 수집 블롭 또는 매니페스트 작업자 실행 간격을 늘리고 싶다면, 기본값(5초)에서 1초로 간격 구성을 업데이트하세요:

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

마이그레이션 로드가 해제된 후에는 이러한 설정을 장기적으로 미세 조정하여 데이터베이스와 레지스트리 인스턴스에서 불필요한 CPU 부하를 피해야 합니다. 성능과 자원 사용의 균형을 맞추는 값으로 간격을 점진적으로 늘릴 수 있습니다.

데이터 일관성 검증

가져온 후 데이터의 일관성을 보장하기 위해 crane validate 도구를 사용하세요. 이 도구는 컨테이너 레지스트리의 모든 이미지 레이어와 매니페스트가 접근 가능하고 올바르게 연결되어 있는지 확인합니다. crane validate를 실행함으로써, 레지스트리의 이미지가 완전하고 접근 가능하며 성공적으로 가져오기를 보장합니다.

정리 정책 검토

대부분의 이미지가 태그가 있는 경우, 가비지 수집으로 저장 공간을 크게 줄일 수 없습니다. 왜냐하면 태그가 없는 이미지만 삭제하기 때문입니다.

사용하지 않는 태그를 제거하기 위한 정리 정책을 구현하여 궁극적으로 이미지를 가비지 수집을 통해 제거하고 저장 공간을 회수할 수 있습니다.

메타데이터 데이터베이스와 백업

메타데이터 데이터베이스가 활성화된 경우, 백업은 이전과 마찬가지로 레지스트리에서 사용되는 객체 저장소뿐만 아니라 데이터베이스도 캡처해야 합니다. 객체 저장소와 데이터베이스의 백업은 레지스트리 상태를 최대한 밀접하게 캡처하도록 조정해야 합니다. 레지스트리를 복원하려면 두 백업을 함께 적용해야 합니다.

레지스트리 다운그레이드

마이그레이션이 완료된 후 레지스트리를 이전 버전으로 다운그레이드하려면, 다운그레이드를 위해 원하는 버전의 백업으로 복원해야 합니다.

문제 해결

오류: 미결 데이터베이스 마이그레이션이 있습니다

레지스트리가 업데이트되고 미결 스키마 마이그레이션이 있는 경우, 레지스트리는 다음과 같은 오류 메시지로 시작하지 않습니다:

FATA[0000] configuring application: 미결 데이터베이스 마이그레이션이 있습니다. 'registry database migrate' CLI 명령을 사용하여 확인하고 적용하십시오.

이 문제를 해결하려면 스키마 마이그레이션 적용하기 단계를 따르세요.

오류: 오프라인 가비지 수집이 더 이상 불가능합니다

레지스트리가 메타데이터 데이터베이스를 사용하고 있고 오프라인 가비지 수집을 실행하려고 시도하는 경우, 레지스트리는 다음 오류 메시지로 실패합니다:

ERRO[0000] 이 파일 시스템은 메타데이터 데이터베이스에 의해 관리되며, 오프라인 가비지 수집이 더 이상 불가능합니다. 더 이상 데이터베이스를 사용하지 않는 경우, 이 로그 메시지의 lock_path에서 파일을 제거하세요. lock_path=/docker/registry/lockfiles/database-in-use

다음 중 하나를 수행해야 합니다:

• 오프라인 가비지 수집을 중지합니다.
• 더 이상 메타데이터 데이터베이스를 사용하지 않는 경우, 오류 메시지에 나타난 lock_path의 잠금 파일을 삭제합니다.
  예를 들어, /docker/registry/lockfiles/database-in-use 파일을 제거합니다.

오류: 읽기 전용 거래에서 <STATEMENT>를 실행할 수 없습니다

레지스트리가 스키마 마이그레이션을 적용하는 데 실패할 수 있으며, 다음 오류 메시지가 표시됩니다:

err="ERROR: 읽기 전용 거래에서 CREATE TABLE을 실행할 수 없습니다 (SQLSTATE 25006)"

또한, 레지스트리가 온라인 가비지 수집을 실행하려고 시도할 때 다음 오류 메시지로 실패할 수 있습니다:

error="작업 처리: 다음 GC 블롭 작업 가져오기: GC 블롭 작업 스캔: ERROR: 읽기 전용 거래에서 SELECT FOR UPDATE를 실행할 수 없습니다 (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.

오류: 모든 리포지토리를 가져올 수 없습니다. 태그 테이블에 항목이 있습니다.

기존 레지스트리를 마이그레이션하려고 시도하고 다음 오류가 발생하는 경우:

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/ee/administration/packages/container_registry_metadata_database.html#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,
     'host' => 'localhost',
     'port' => 5432,
     'user' => 'registry-database-user',
     'password' => 'registry-database-password',
     'dbname' => 'registry-database-name',
     'sslmode' => 'require', # PostgreSQL 문서에서 추가 정보를 참조하십시오 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/path/to/cert.pem',
     'sslkey' => '/path/to/private.key',
     'sslrootcert' => '/path/to/ca.pem'
   }
   

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에 위치해 있습니다.

메타데이터 관리 문제로 인해 레지스트리가 시작되지 않음

레지스트리가 다음 오류로 인해 시작되지 않을 수 있습니다:

오류: 레지스트리 파일 시스템 메타데이터가 사용 중입니다. 데이터베이스를 활성화하기 전에 데이터를 가져와야 합니다.

이 오류는 구성에서 데이터베이스가 활성화된 상태일 때 발생합니다, registry['database'] = { 'enabled' => true }

하지만 메타데이터 데이터베이스로 기존 데이터를 마이그레이션하지 않았습니다.

오류: 레지스트리 메타데이터 데이터베이스가 사용 중입니다. 데이터베이스를 활성화해야 합니다.

이 오류는 메타데이터 데이터베이스로 기존 데이터 마이그레이션을 완료했지만 구성에서 데이터베이스를 활성화하지 않았을 때 발생합니다.

잠금 파일을 확인하거나 생성하는 데 문제가 발생했습니다

다음 오류 중 하나가 발생하면:

• 파일 시스템 메타데이터가 잠금되었는지 확인할 수 없습니다
• 데이터베이스 메타데이터가 잠금되었는지 확인할 수 없습니다
• 데이터베이스 전용 사용을 위해 파일 시스템을 표시하지 못했습니다
• 파일 시스템만 사용하기 위해 표시하지 못했습니다

레지스트리가 구성된 rootdirectory에 접근할 수 없습니다. 이전에 작동하던 레지스트리가 있었다면 이 오류는 발생할 가능성이 적습니다. 오류 로그를 검토하여 잘못된 구성 문제를 확인하세요.