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

Tier: Free, Premium, Ultimate Offering: Self-managed Status: Beta
caution
메타데이터 데이터베이스는 베타 기능입니다. 프로덕션 환경에서 레지스트리 데이터베이스를 활성화하기 전에 문서를 주의 깊게 확인하세요! 레지스트리의 가져오기 또는 작업 중에 문제가 발생하는 경우 피드백 이슈에 댓글을 추가하세요.

메타데이터 데이터베이스를 사용하면 온라인 가비지 수집 및 여러 레지스트리 작업의 효율성을 높일 수 있는 새로운 레지스트리 기능이 가능해집니다. Self-managed 배포의 레지스트리 메타데이터 데이터베이스 기능 관련 작업은 에픽 5521에서 추적됩니다.

기본적으로 컨테이너 레지스트리는 객체 리포지터리를 사용하여 컨테이너 이미지와 관련된 메타데이터를 보관합니다. 이 메타데이터 저장 방식은 효율적인 데이터 접근성을 제한하며, 특히 태그를 나열할 때와 같이 여러 이미지에 걸친 데이터의 경우에 더욱 그러합니다. 이 데이터를 저장하기 위해 데이터베이스를 사용하면 온라인 가비지 수집과 같은 많은 새로운 기능이 가능해집니다. 이 기능을 사용하면 이전 데이터를 자동으로 제거할 수 있으며, 중단 시간이 없습니다.

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

알려진 제한 사항

  • 온라인 마이그레이션 지원이 없음
  • Geo 지원이 확인되지 않음
  • 레지스트리 데이터베이스 마이그레이션이 버전 업그레이드시 매뉴얼으로 실행되어야 함 마이그레이션 지원

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

일부 데이터베이스 지원 기능은 GitLab.com에서만 활성화되어 있으며, 레지스트리 데이터베이스에 대한 자동 데이터베이스 프로비저닝은 사용할 수 없습니다. 컨테이너 레지스트리 데이터베이스와 관련된 기능 지원 표를 피드백 이슈에서 확인하세요.

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

사전 요구 사항:

  • 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', # SSL에 대한 추가 정보는 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', # SSL에 대한 추가 정보는 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 및 구성된 객체 리포지터리 간의 네트워크 지연.

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

일회성 마이그레이션

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

  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', # SSL에 대한 추가 정보는 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', # SSL에 대한 추가 정보는 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 구성 다시 적용하세요.

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

세 단계의 마이그레이션

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

note
사용자들은 1단계 가져오기가 시간당 2에서 4TB의 속도로 완료되었다고 보고했습니다. 더 느린 속도로는 100TB 이상의 데이터를 가진 레지스트리는 48시간보다 더 오랜 시간이 걸릴 수 있습니다.
리포지터리 사전 가져오기 (1단계)

큰 인스턴스의 경우, 이 명령어는 레지스트리의 크기에 따라 몇 시간에서 며칠이 걸릴 수 있습니다. 1단계가 완료되는 동안 레지스트리를 계속해서 평소와 같이 사용할 수 있습니다.

caution
마이그레이션을 다시 시작할 수 없으므로 마이그레이션이 완료될 때까지 마이그레이션을 계속하는 것이 중요합니다. 작업을 중지해야 하는 경우에도이 단계를 다시 시작해야 합니다.

  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
note
가능한 한 빨리 다음 단계를 계획하고 다운타임을 줄이기 위해 노력해야 합니다. 1단계와 2단계 사이에 레지스트리에 쓰인 새 데이터는 2단계에 더 많은 시간이 소요되도록 합니다.
모든 리포지터리 데이터 가져오기 (2단계)

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

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

    /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단계)

이제 레지스트리는 메타데이터 데이터베이스를 완전히 사용하고 있지만 아직 사용되지 않은 레이어 blob에 대한 액세스 권한이 없습니다. 프로세스를 완료하려면 마이그레이션의 최종 단계를 실행하세요: 

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

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

스키마 마이그레이션 관리

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

스키마 마이그레이션 적용

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

    sudo gitlab-ctl registry-database migrate up

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

note
migrate up 명령에는 마이그레이션이 어떻게 적용되는지를 제어하는 데 사용할 수있는 몇 가지 추가 플래그가 있습니다. 세부 정보는 sudo gitlab-ctl registry-database migrate up --help을 실행하여 확인하세요.

스키마 마이그레이션 취소

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

  1. 레지스트리 데이터베이스 스키마 마이그레이션을 되돌립니다: 

    sudo gitlab-ctl registry-database migrate down
note
migrate down 명령에는 몇 가지 추가 플래그가 있습니다. 자세한 내용은 sudo gitlab-ctl registry-database migrate down --help를 실행하여 확인하세요.

문제 해결

보류 중인 데이터베이스 마이그레이션 오류

레지스트리가 업데이트되었고 보류 중인 스키마 마이그레이션이 있는 경우, 다음과 같은 오류 메시지로 레지스트리를 시작할 수 없습니다: 

FATA[0000] 애플리케이션 구성 중: 보류 중인 데이터베이스 마이그레이션이 있습니다. 'registry database migrate' CLI 명령을 사용하여 확인하고 적용하세요

이 문제를 해결하려면 스키마 마이그레이션을 적용하는 단계를 따릅니다.

오프라인 가비지 수집 불가 오류

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

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

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

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