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

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

메타데이터 데이터베이스는 온라인 가비지 수집을 포함한 여러 레지스트리 기능을 활성화하고 많은 레지스트리 작업의 효율성을 높입니다. 레지스트리 메타데이터 데이터베이스 기능의 Self-Managed형 릴리스 작업은 epic 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 재구성을 실행하세요.

기존 레지스트리

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

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

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

원 단계 마이그레이션

caution
데이터베이스 마이그레이션 중에 레지스트리는 종료되거나 읽기 전용 모드로 유지되어야 합니다. 마이그레이션 중에 레지스트리에 쓰기 작업이 필요하지 않고 레지스트리에 상대적으로 적은 양의 데이터가 포함되어 있다면 이 방법을 선택하세요.

  1. /etc/gitlab/gitlab.rb 파일에 database 섹션을 추가하여 메타데이터 데이터베이스가 비활성화되도록 시작하세요: 

    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. 레지스트리가 읽기 전용 모드로 설정되었는지 확인하세요.

    /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 재구성을 실행하세요.

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

세 단계 마이그레이션

기존 컨테이너 레지스트리 데이터를 마이그레이션하는 방법을 따르세요. 이 프로시저는 데이터 양이 많을 때 또는 마이그레이션을 완료하는 동안 다운타임을 최소화하려고 할 때 추천됩니다.

note
사용자들은 단계 1의 가져오기가 1시간당 2TB에서 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' => '/경로/to/cert.pem',
  'sslkey' => '/경로/to/private.key',
  'sslrootcert' => '/경로/to/ca.pem'
}
  2. 파일을 저장하고 GitLab을 다시 구성하세요.
  3. 아직 수행하지 않았다면 스키마 마이그레이션 적용하세요.

  4. 마이그레이션의 첫 번째 단계를 실행하세요: 

    sudo gitlab-ctl registry-database import --step-one
note
가능한 한 빨리 다음 단계를 일정에 등록하면 downtime이 필요한 양을 줄일 수 있습니다. 이상적으로, 단계 한이 완료된 후 1주일 이내에 진행하세요. 단계 한과 단계 둘 사이에 새로운 데이터를 쓰면 단계 둘이 더 오래 걸릴 수 있습니다.
모든 리포지터리 데이터 가져오기 (단계 2)

이 단계는 레지스트리가 읽기 전용 모드로 설정되거나 중지되어야 합니다. 단계 2가 실행되는 동안 downtime에 충분한 시간을 허용하세요.

  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. 마이그레이션의 두 번째 단계를 실행하세요 

    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' => '/경로/to/cert.pem',
  'sslkey' => '/경로/to/private.key',
  'sslrootcert' => '/경로/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

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

스키마 마이그레이션 관리

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

스키마 마이그레이션 적용

  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를 실행하세요.

문제 해결

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