메타데이터 데이터베이스는 성능을 개선하고 새 기능을 추가하는 컨테이너 레지스트리에 대한 여러 개선 사항을 제공합니다. GitLab Self-Managed의 레지스트리 메타데이터 데이터베이스 기능 릴리스 작업은 에픽 5521에서 추적됩니다.

기본적으로 컨테이너 레지스트리는 오브젝트 스토리지 또는 로컬 파일 시스템을 사용하여 컨테이너 이미지와 관련된 메타데이터를 유지합니다. 이 메타데이터 저장 방법은 특히 태그를 나열할 때와 같이 여러 이미지에 걸친 데이터를 효율적으로 액세스하는 방법을 제한합니다. 데이터베이스를 사용하여 이 데이터를 저장하면 제로 다운타임으로 오래된 데이터를 자동으로 제거하는 온라인 가비지 컬렉션을 포함한 많은 새 기능이 가능해집니다.

이 데이터베이스는 레지스트리가 이미 사용하는 스토리지와 함께 작동하지만 오브젝트 스토리지나 파일 시스템을 대체하지 않습니다. 메타데이터 데이터베이스로 메타데이터 가져오기를 수행한 후에도 스토리지 솔루션을 계속 유지해야 합니다.

Helm Charts 설치의 경우, Helm Charts 문서의 컨테이너 레지스트리 메타데이터 데이터베이스 관리를 참조하세요.

개선 사항#

메타데이터 데이터베이스 아키텍처는 레거시 메타데이터 스토리지로는 사용할 수 없는 성능 개선, 버그 수정 및 새 기능을 지원합니다. 이러한 개선 사항에는 다음이 포함됩니다:

• 자동 온라인 가비지 컬렉션
• 리포지터리, 프로젝트 및 그룹에 대한 스토리지 사용량 가시성
• 이미지 서명
• 리포지터리 이동 및 이름 바꾸기
• 보호된 태그
• 정리 정책에 대한 성능 개선, 대규모 리포지터리의 성공적인 정리 가능
• 리포지터리 태그 나열에 대한 성능 개선
• 태그 게시 타임스탬프 추적 및 표시 (이슈 290949 참조)
• 이름 이외의 추가 속성으로 리포지터리 태그 정렬

레거시 메타데이터 스토리지의 기술적 제약으로 인해 새 기능은 메타데이터 데이터베이스 버전에서만 구현됩니다. 보안 관련이 아닌 버그 수정은 메타데이터 데이터베이스 버전으로 제한될 수 있습니다.

알려진 제한 사항#

• 기존 레지스트리의 메타데이터 가져오기에는 읽기 전용 시간이 필요합니다.
• 18.3 이전에는 버전을 업그레이드할 때 레지스트리 일반 스키마 및 배포 후 데이터베이스 마이그레이션을 수동으로 실행해야 합니다.
• 멀티 노드 Linux 패키지 환경에서 업그레이드 중 레지스트리 제로 다운타임에 대한 보장이 없습니다.
• 기존 레지스트리의 메타데이터 가져오기 중에 이미지 태그의 createdAt 및 publishedAt 타임스탬프 값이 가져오기 날짜로 설정됩니다. 이는 일관성을 보장하기 위한 의도적인 것으로, 레거시 레지스트리는 모든 이미지에 대한 태그 게시 날짜를 수집하지 않기 때문입니다. 일부 이미지에는 메타데이터에 빌드 날짜가 있지만 많은 이미지에는 없습니다. 자세한 내용은 이슈 1384를 참조하세요.

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

기존 레지스트리에서 메타데이터 데이터베이스로 메타데이터를 가져오고 온라인 가비지 컬렉션을 사용할 수 있습니다.

일부 데이터베이스 활성화 기능은 GitLab.com에서만 활성화되며 레지스트리 데이터베이스의 자동 데이터베이스 프로비저닝을 사용할 수 없습니다. 컨테이너 레지스트리 데이터베이스와 관련된 기능 상태는 피드백 이슈의 기능 지원 표를 검토하세요.

Linux 패키지 설치에 메타데이터 데이터베이스 활성화#

사전 요구 사항:

• GitLab 17.5가 최소 요구 버전이지만, 추가 개선 사항 및 더 쉬운 구성으로 인해 GitLab 18.3 이상을 권장합니다.
• 버전 요구 사항 내의 PostgreSQL 데이터베이스. 레지스트리 노드에서 액세스할 수 있어야 합니다.
• 외부 데이터베이스를 사용하는 경우 먼저 외부 데이터베이스 연결을 설정해야 합니다. 자세한 내용은 외부 데이터베이스 사용을 참조하세요.

시작하기 전에#

• 데이터베이스를 활성화한 후에는 계속 사용해야 합니다. 이제 데이터베이스가 레지스트리 메타데이터의 소스이며, 이 시점 이후에 비활성화하면 데이터베이스가 활성화된 동안 작성된 모든 이미지에 대한 레지스트리의 가시성이 손실됩니다.
• 오프라인 가비지 컬렉션은 더 이상 필요하지 않습니다. 데이터베이스가 활성화되면 GitLab에 포함된 가비지 컬렉션 명령이 안전하게 종료되지만, 업스트림 레지스트리에서 제공하는 것과 같은 서드파티 명령은 태그가 지정된 이미지와 관련된 데이터를 삭제합니다.
• 오프라인 가비지 컬렉션을 자동화하지 않았는지 확인합니다. 특히 서드파티 명령을 사용하는 경우.
• 프로세스를 가속화하기 위해 먼저 레지스트리 스토리지를 줄일 수 있습니다.
• 가능하면 컨테이너 레지스트리 데이터를 백업합니다.
• 컨테이너 레지스트리 알림을 구성합니다.

새 설치에 데이터베이스 활성화#

컨테이너 레지스트리에 데이터를 작성한 적이 없는 설치의 경우 가져오기가 필요하지 않습니다. 레지스트리에 데이터를 작성하기 전에 데이터베이스만 활성화하면 됩니다.

자세한 내용은 새 설치 지침을 참조하세요.

기존 레지스트리에 데이터베이스 활성화#

1단계 가져오기 방법 또는 3단계 가져오기 방법을 사용하여 기존 컨테이너 레지스트리 메타데이터를 가져올 수 있습니다. 가져오기 기간에 영향을 미치는 몇 가지 요소가 있습니다:

• 레지스트리의 태그가 지정된 이미지 수.
• 기존 레지스트리 데이터의 크기.
• PostgreSQL 인스턴스의 사양.
• 실행 중인 레지스트리 인스턴스 수.
• 레지스트리, PostgreSQL 및 구성된 스토리지 간의 네트워크 지연.

가져오기 전에 다음을 수행할 필요가 없습니다:

• 추가 오브젝트 스토리지 또는 파일 시스템 공간 할당: 가져오기는 이 스토리지에 중요한 쓰기를 하지 않습니다.
• 오프라인 가비지 컬렉션 실행: 해롭지는 않지만 오프라인 가비지 컬렉션은 이 명령 실행에 소비한 시간을 회수할 만큼 가져오기를 충분히 단축하지 않습니다.

올바른 가져오기 방법 선택#

오프라인 가비지 컬렉션을 정기적으로 실행하는 경우, 1단계 가져오기 방법을 사용합니다. 이 방법은 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 기간 문자열을 참조하세요.

가져오기 후#

대규모 가져오기 완료 후, 수십만에서 수백만 개의 blob이 가비지 컬렉션 검토 대기열에 추가될 수 있습니다. 이는 정상입니다.

태그된 이미지가 dangling blob 목록 생성 전에 가져오기되기 때문에, 가비지 컬렉터는 처음에 태그된 이미지에 의해 여전히 참조되는 blob을 검토합니다. 가비지 컬렉션은 이 blob들을 대기열에서 제거하지만 스토리지에서 삭제하지는 않습니다.

스토리지는 가비지 컬렉터가 dangling blob에 도달한 후에만 감소합니다. 가비지 컬렉터는 이미지 blob과의 간섭을 방지하기 위해 검토를 지연하기 때문에 가져오기 후 레지스트리 스토리지가 감소하는 데 48시간 이상이 걸릴 수 있습니다.

가져오기 후 가비지 컬렉션 백로그를 모니터링하고 관리하려면:

• 온라인 가비지 컬렉션 상태 확인으로 검토 대기열의 크기와 상태를 확인합니다.

• 가비지 컬렉터 워커 간격 조정으로 대규모 백로그 처리를 일시적으로 가속화합니다.

데이터베이스 마이그레이션#

컨테이너 레지스트리는 두 가지 유형의 마이그레이션을 지원합니다:

• 일반 스키마 마이그레이션: 새 애플리케이션 코드를 배포하기 전에 실행해야 하는 데이터베이스 구조 변경으로, 사전 배포 마이그레이션이라고도 합니다. 배포 지연을 방지하기 위해 빠르게(몇 분 이하) 실행되어야 합니다.
• 배포 후 마이그레이션: 애플리케이션이 실행 중인 동안 실행할 수 있는 데이터베이스 구조 변경. 시작 지연 및 장기 업그레이드 다운타임을 방지하기 위해 대규모 테이블에 인덱스 생성과 같은 더 긴 작업에 사용됩니다.

기본적으로 레지스트리는 일반 스키마 및 배포 후 마이그레이션을 동시에 적용합니다. 업그레이드 중 다운타임을 줄이기 위해 배포 후 마이그레이션을 건너뛰고 애플리케이션이 시작된 후 수동으로 적용할 수 있습니다.

데이터베이스 마이그레이션 적용#

애플리케이션이 시작되기 전에 일반 스키마 및 배포 후 마이그레이션을 모두 적용하려면:

1. 데이터베이스 마이그레이션을 실행합니다:

   sudo -u registry gitlab-ctl registry-database migrate up
   

배포 후 마이그레이션을 건너뛰려면:

1. 일반 스키마 마이그레이션만 실행합니다:

   sudo -u registry gitlab-ctl registry-database migrate up --skip-post-deployment
   

   --skip-post-deployment 플래그 대신 SKIP_POST_DEPLOYMENT_MIGRATIONS 환경 변수를 true로 설정할 수도 있습니다:

   SKIP_POST_DEPLOYMENT_MIGRATIONS=true sudo -u registry gitlab-ctl registry-database migrate up
   

2. 애플리케이션을 시작한 후 대기 중인 배포 후 마이그레이션을 적용합니다:

   sudo -u registry gitlab-ctl registry-database migrate up
   

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

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

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

가져오기를 완료한 후 가비지 컬렉션 큐가 소진되면서 데이터베이스가 높은 부하를 경험하는 기간을 예상합니다. 이 높은 부하는 온라인 가비지 컬렉터가 대기 중인 태스크를 처리하는 과정에서 개별 데이터베이스 호출 수가 많기 때문입니다.

오류나 경고에 대한 PostgreSQL 및 레지스트리 로그를 정기적으로 확인합니다. 레지스트리 로그에서 component=registry.gc.*로 필터링된 로그에 특히 주의합니다.

메트릭 추적#

Prometheus 및 Grafana와 같은 모니터링 도구를 사용하여 registry_gc_* 프리픽스를 가진 메트릭에 초점을 맞춰 가비지 컬렉션 메트릭을 시각화하고 추적합니다. 여기에는 삭제로 표시된 오브젝트 수, 성공적으로 삭제된 오브젝트, 실행 간격 및 기간이 포함됩니다. Prometheus를 활성화하는 방법은 레지스트리 디버그 서버 활성화를 참조하세요.

태스크 큐 모니터링#

블롭 및 매니페스트에 대한 가비지 컬렉션 태스크 큐의 건강 및 상태를 모니터링합니다.

온라인 가비지 컬렉션의 건강 확인#

다음 쿼리는 10번 이상 재시도된 태스크 또는 24시간 이상 검토 대상인 태스크를 반환합니다. 온라인 가비지 컬렉터는 24시간 내에 실패 시도가 적은 항목을 검토용으로 가져와야 합니다. 행이 반환되면 온라인 가비지 컬렉터의 건강 상태를 조사합니다.

매니페스트의 경우:

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;

이러한 쿼리가 행을 반환하면 가비지 컬렉션과 관련된 메시지에 대한 레지스트리 로그를 확인합니다. component="registry.gc.*로 항목을 필터링하고 오류 메시지를 조사합니다.

gc_manifest_review_queue 및 gc_blob_review_queue의 필터링되지 않은 크기는 온라인 가비지 컬렉터의 건강 상태를 나타내는 좋은 지표가 아닙니다. 이러한 큐는 활성 레지스트리에서 완전히 지워지지 않습니다.

검토 대상인 대량의 태스크도 반드시 우려할 필요는 없습니다. 가비지 컬렉터는 활동 급증으로 인한 항목을 처리 중일 수 있습니다.

마찬가지로 이러한 태스크의 created_at 날짜만으로는 좋은 건강 지표가 아닙니다. 이벤트가 동일한 블롭 또는 매니페스트를 큐에 추가할 때 기존 태스크의 review_after가 업데이트되어 검토가 연기됩니다. 중복 태스크는 생성되지 않습니다.

이는 여러 번 발생할 수 있으므로 수개월 전에 생성된 태스크는 우려할 필요가 없습니다.

온라인 가비지 컬렉션 관련 정보 쿼리#

다음 쿼리를 실행하여 검토 대상인 태스크 수를 확인합니다:

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

일반적으로 이러한 쿼리는 상대적으로 낮은 카운트를 반환해야 하며, 종종 0에 가깝습니다. 그러나 다음과 같은 경우 이러한 쿼리가 더 큰 값을 반환할 수 있습니다:

• 가져오기가 24~48시간 전에 시작된 경우
• 대량의 태그가 삭제되거나 컨테이너 리포지터리가 제거된 경우
• 온라인 가비지 컬렉션이 장기간 비활성화된 경우

가비지 컬렉터 워커 간격 조정#

검토 대상인 태스크 수가 높게 유지되고 가비지 컬렉션 블롭 또는 매니페스트 워커 실행 사이의 빈도를 높이고 싶다면 기본값(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>'
}

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

메타데이터 데이터베이스가 활성화되면 백업은 이전과 같이 레지스트리에서 사용하는 오브젝트 스토리지뿐만 아니라 데이터베이스도 캡처해야 합니다. 오브젝트 스토리지와 데이터베이스의 백업은 서로 가능한 한 가까운 레지스트리 상태를 캡처하도록 조율되어야 합니다. 레지스트리를 복원하려면 두 백업을 함께 적용해야 합니다.

레지스트리 다운그레이드#

가져오기 완료 후 레지스트리를 이전 버전으로 다운그레이드하려면 원하는 버전의 백업으로 복원해야 합니다.

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 --&gt; S_Reg</code></pre></details></div>

각 사이트에 별도의 데이터베이스 인스턴스를 사용하는 이유:

기본 GitLab 데이터베이스가 보조 사이트에 읽기 전용으로 복제됩니다.
이 복제는 레지스트리 데이터베이스에 대해 선택적으로 비활성화할 수 없습니다.
컨테이너 레지스트리는 두 사이트 모두의 데이터베이스에 대한 쓰기 액세스가 필요합니다.
동일한 설정은 Geo 사이트 간에 최대한의 동등성을 보장합니다.

오브젝트 스토리지 메타데이터로 되돌리기#
메타데이터 가져오기를 완료한 후 레지스트리를 오브젝트 스토리지 메타데이터를 사용하도록 되돌릴 수 있습니다.
Warning
오브젝트 스토리지 메타데이터로 되돌리면 가져오기 완료와 이 되돌리기 작업 사이에 추가되거나 삭제된 컨테이너 이미지, 태그 또는 리포지터리를 사용할 수 없게 됩니다.

오브젝트 스토리지 메타데이터로 되돌리려면:


마이그레이션 전에 찍은 백업을 복원합니다.


/etc/gitlab/gitlab.rb 파일에 다음 구성을 추가합니다:
registry['database'] = {
  'enabled' => false,
}



파일을 저장하고 GitLab을 재구성합니다.


문제 해결#
오류 및 문제 해결 솔루션과 해결 방법을 검토하려면 컨테이너 레지스트리 메타데이터 데이터베이스 문제 해결을 참조하세요.