• 알려진 제한 사항
• 메타데이터 데이터베이스 기능 지원
• Linux 패키지 설치를 위한 메타데이터 데이터베이스 활성화
  • 시작하기 전에
  • 새로운 설치
  • 기존 레지스트리
    • 하나의 단계로 마이그레이션
    • 세 단계로 마이그레이션
      • 리포지토리 사전 가져오기 (첫 번째 단계)
      • 모든 저장소 데이터 가져오기 (두 번째 단계)
      • 나머지 데이터 가져오기 (세 번째 단계)
• 스키마 마이그레이션 관리
  • 스키마 마이그레이션 적용
  • 스키마 마이그레이션 되돌리기
• 문제 해결
  • there are pending database migrations 오류
  • offline garbage collection is no longer possible 오류

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

• GitLab 16.4에 도입되었으며, Self-Managed GitLab 인스턴스를 위한 베타 기능으로 제공됩니다.

경고: 메타데이터 데이터베이스는 베타 기능입니다. 운영 환경에서 레지스트리 데이터베이스를 활성화하기 전에 문서를 주의 깊게 검토하세요! 레지스트리의 가져오기 또는 작동에 문제가 발생하는 경우, 피드백 이슈에 의견을 추가하세요.

메타데이터 데이터베이스를 사용하면 온라인 가비지 수집 및 다양한 레지스트리 작업의 효율성을 향상시키는 등 여러 새로운 레지스트리 기능을 사용할 수 있습니다. 레지스트리 메타데이터 데이터베이스 기능의 Self-Managed 릴리스 작업은 에픽 5521에서 추적됩니다.

기본적으로 컨테이너 레지스트리는 컨테이너 이미지와 관련된 메타데이터를 지속시키기 위해 객체 저장소를 사용합니다. 이 메타데이터 저장 방식은 효율적으로 데이터에 액세스하는 데 제약을 가지며, 특히 태그를 나열할 때와 같이 여러 이미지에 걸친 데이터에 대해 특히 제한적입니다. 이러한 데이터를 저장하기 위해 데이터베이스를 사용함으로써 오프라인 가비지 수집을 포함하여 다양한 새로운 기능이 가능해집니다. (온라인 가비지 수집을 참조하세요)

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

알려진 제한 사항

• 온라인 마이그레이션 지원 불가
• Geo 지원이 확인되지 않았습니다.
• 버전 업그레이드 시 레지스트리 데이터베이스 마이그레이션이 수동으로 실행되어야 합니다.

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

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

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

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

전제 조건:

• GitLab 16.7 이상
• PostgreSQL 데이터베이스 버전 12 이상. 레지스트리 노드에서 액세스할 수 있어야 합니다.

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

• 새로운 설치 또는 컨테이너 레지스트리를 처음으로 활성화하는 경우.
• 기존 컨테이너 이미지를 메타데이터 데이터베이스로 마이그레이션:
  • 원 스텝 마이그레이션. 상대적으로 작은 레지스트리 또는 다운 타임을 피할 요구 사항이 없는 경우에만 권장됩니다.
  • 삼 스텝 마이그레이션. 큰 컨테이너 레지스트리에 권장되는 방법입니다.

시작하기 전에

• 데이터베이스를 활성화한 후에는 계속 사용해야 합니다. 데이터베이스가 레지스트리 메타데이터의 소스가 되며 데이터베이스를 비활성화하는 경우, 레지스트리는 데이터베이스가 활성화된 동안에 작성된 모든 이미지를 볼 수 없게 됩니다.
• 가져오기 단계가 완료된 후에는 오프라인 가비지 수집을 실행해서는 안 됩니다. 해당 명령은 메타데이터 데이터베이스를 사용하는 레지스트리와 호환되지 않으며 데이터를 삭제합니다.
• 오프라인 가비지 수집이 자동화되지 않았는지 확인하세요.
• 레지스트리 저장소의 저장 공간을 줄이기 위해 저장소를 먼저 줄일 수 있습니다.
• 가능하다면 컨테이너 레지스트리 데이터를 백업하세요.

새로운 설치

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

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을 다시 구성하세요.

기존 레지스트리

기존 컨테이너 레지스트리 데이터를 하나의 단계로 또는 세 단계로 마이그레이션할 수 있습니다. 마이그레이션 기간에 영향을 미치는 몇 가지 요소가 있습니다.

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

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

하나의 단계로 마이그레이션

경고: 경고: 마이그레이션 중에 레지스트리를 종료하거나 읽기 전용 모드로 유지해야 합니다. 마이그레이션 중 레지스트리에 쓰지 않아도 되는 경우에만이 방법을 선택하세요. 그리고 레지스트리에는 비교적 적은 양의 데이터가 포함되어 있어야 합니다.

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 섹션을 추가하십시오. 예를 들어, gcs를 사용하는 gs://my-company-container-registry 버킷에서 백업되는 레지스트리의 경우, 구성은 다음과 같을 수 있습니다:

   ## 객체 저장소 - 컨테이너 레지스트리
   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을 다시 구성하십시오.

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

세 단계로 마이그레이션

기존 컨테이너 레지스트리 데이터를 마이그레이션하는 방법을 따르세요. 이 프로시저는 데이터 양이 큰 경우나 마이그레이션을 완료하는 동안 다운 타임을 최소화하려는 경우에 권장됩니다.

참고: 사용자들은 첫 번째 단계의 가져오기가 시간당 2~4 TB의 속도로 완료된 것으로 보고했습니다. 더 느린 속도에서는 100TB 이상의 데이터를 포함하는 레지스트리에는 48시간보다 더 오랜 시간이 걸릴 수 있습니다.

리포지토리 사전 가져오기 (첫 번째 단계)

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

경고: 이 작업을 중지하더라도 다시 시작할 수 있는 방법은 현재 아직 없으므로 작업을 완료하기 위해서은 중단하지 않도록 주의해야 합니다.

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. 파일을 저장하고 GitLab을 다시 구성하십시오.
3. 아직 수행하지 않았다면 스키마 마이그레이션 적용하십시오.

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

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

참고: 가능한 한 빨리 다음 단계를 일정에 넣도록 노력하십시오. 첫 번째 단계와 두 번째 단계 사이에 레지스트리에 새 데이터를 쓰면 두 번째 단계가 더 많은 시간이 걸립니다.

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

이 단계에서는 레지스트리를 중지하거나 읽기 전용 모드로 설정해야 합니다. 두 번째 단계가 실행되는 동안 다운타임에 충분한 시간을 확보하세요.

1. 레지스트리가 읽기 전용 모드로 설정되었는지 확인하세요.

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

   ## Object Storage - Container Registry
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => true # 반드시 true로 설정되어야 합니다.
       }
     }
   }
   

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

3. 마이그레이션의 두 번째 단계를 실행하세요.

   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 documentation에서 확인하세요 https://www.postgresql.org/docs/current/libpq-ssl.html.
     'sslcert' => '/cert.pem의/경로',
     'sslkey' => '/private.key의/경로',
     'sslrootcert' => '/ca.pem의/경로'
   }
   
   ## Object Storage - Container Registry
   registry['storage'] = {
     'gcs' => {
       'bucket' => "my-company-container-registry",
       'chunksize' => 5242880
     },
     'maintenance' => { # 이 섹션은 제거할 수 있습니다.
       'readonly' => {
         'enabled' => false
       }
     }
   }
   

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

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

나머지 데이터 가져오기 (세 번째 단계)

이제 레지스트리는 메타데이터에 완전히 의존하고 있지만, 여전히 사용되지 않은 레이어 블롭들에 대한 접근 권한이 없습니다.

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

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

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

스키마 마이그레이션 관리

컨테이너 레지스트리 메타데이터 데이터베이스의 스키마 마이그레이션을 실행하려면 다음 명령을 사용하세요. 레지스트리가 활성화되어 있고 구성 섹션이 데이터베이스 섹션으로 채워져 있어야 합니다.

스키마 마이그레이션 적용

1. 레지스트리 데이터베이스 스키마 마이그레이션을 실행하세요.

   sudo gitlab-ctl registry-database migrate up
   

2. 레지스트리가 실행 중이라면 중지되어야 합니다. 프로세스가 완료될 때까지 확인을 위해 y를 입력하세요.

참고: migrate up 명령에는 마이그레이션을 적용하는 방법을 제어하는 추가 플래그가 있습니다. 자세한 내용은 세부 정보를 위해 sudo gitlab-ctl registry-database migrate up --help을 실행하세요.

스키마 마이그레이션 되돌리기

문제가 발생한 경우 스키마 마이그레이션을 되돌릴 수 있지만, 이는 복구할 수 없는 작업입니다. 데이터베이스를 사용하는 동안 새 이미지를 푸시했다면, 이후에는 더 이상 액세스할 수 없습니다.

1. 레지스트리 데이터베이스 스키마 마이그레이션을 되돌리세요:

   sudo gitlab-ctl registry-database migrate down
   

참고: migrate down 명령에는 추가 플래그가 있습니다. 자세한 내용은 sudo gitlab-ctl registry-database migrate down --help을 실행하세요.

문제 해결

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

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

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 파일을 제거하세요.