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

Tier: Free, Premium, Ultimate Offering: Self-managed

GitLab 16.4에서 도입됨 - 베타 기능으로.

GitLab 17.3에서 일반 제공.

메타데이터 데이터베이스는 온라인 가비지 수집을 포함하여 많은 새로운 레지스트리 기능을 가능하게 하며, 많은 레지스트리 작업의 효율성을 높입니다. 이 페이지는 데이터베이스를 생성하는 방법에 대한 정보를 포함하고 있습니다.

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

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

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

데이터베이스 생성

데이터베이스와 역할을 수동으로 생성하려면 아래 단계를 따르세요.

이 지침은 번들된 PostgreSQL 서버를 사용한다고 가정합니다. 자체 서버를 사용하는 경우 연결하는 방법에 약간의 차이가 있을 수 있습니다.

데이터베이스 비밀번호로 비밀을 생성합니다:

kubectl create secret generic RELEASE_NAME-registry-database-password --from-literal=password=randomstring

데이터베이스 인스턴스에 로그인합니다:

kubectl exec -it $(kubectl get pods -l app.kubernetes.io/name=postgresql -o custom-columns=NAME:.metadata.name --no-headers) -- bash

PGPASSWORD=${POSTGRES_POSTGRES_PASSWORD} psql -U postgres -d template1

데이터베이스 사용자를 생성합니다:
```
CREATE ROLE registry WITH LOGIN;
```

데이터베이스 사용자 비밀번호를 설정합니다.

비밀번호 가져오기:

kubectl get secret RELEASE_NAME-registry-database-password -o jsonpath="{.data.password}" | base64 --decode

psql 프롬프트에서 비밀번호 설정:
```
\password registry
```

데이터베이스를 생성합니다:

CREATE DATABASE registry WITH OWNER registry;

PostgreSQL 명령줄에서 안전하게 종료한 후 exit를 사용하여 컨테이너에서 종료합니다:
```
template1=# exit
...@gitlab-postgresql-0/$ exit
```

Helm 차트 설치를 위한 메타데이터 데이터베이스 활성화

전제 조건:

GitLab 17.3 이상
PostgreSQL 데이터베이스 버전 12 이상, 레지스트리 Pods에서 접근 가능
Kubernetes 클러스터에 대한 액세스 및 Helm 배포 로컬
레지스트리 Pods에 대한 SSH 액세스

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

새로운 설치 또는 컨테이너 레지스트리를 처음 활성화하는 경우.
기존 컨테이너 이미지를 메타데이터 데이터베이스로 마이그레이션:
- 일단계 마이그레이션. 비교적 작은 레지스트리 또는 다운타임을 피할 필요가 없는 경우에만 권장됩니다.
- 삼단계 마이그레이션. 더 큰 컨테이너 레지스트리에 권장됩니다.

다양한 테스트 및 사용자 레지스트리에 대한 가져오기 시간 목록은 이 표에서 확인하세요. 귀하의 레지스트리 배치는 독특하며, 귀하의 가져오기 시간은 문제에 보고된 것보다 더 길 수 있습니다.

시작하기 전에

레지스트리 관리 가이드의 시작하기 전에 섹션을 읽으세요.

새 설치

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

데이터베이스 및 Kubernetes 비밀 만들기.
릴리스를 위한 현재 Helm 값을 가져오고 파일에 저장합니다.
예를 들어, gitlab이라는 이름의 릴리스와 values.yml이라는 이름의 파일에 대해:
```
helm get values gitlab > values.yml
```

values.yml 파일에 다음 줄을 추가합니다:

registry:
  enabled: true
  database:
    enabled: true
    name: registry  # 위에서 생성한 데이터베이스 이름과 일치해야 함
    user: registry  # 위에서 생성한 데이터베이스 사용자 이름과 일치해야 함
    password:
      secret: gitlab-registry-database-password # 비밀 이름과 일치해야 함
      key: password  # 비밀번호를 읽기 위한 비밀 키와 일치해야 함
    sslmode: verify-full
    ssl:
      secret: gitlab-registry-postgresql-ssl # 이 비밀을 수동으로 생성해야 함
      clientKey: client-key.pem
      clientCertificate: client-cert.pem
      serverCA: server-ca.pem
    migrations:
      enabled: true  # 이 옵션은 레지스트리 배포의 일환으로 스키마 마이그레이션을 실행합니다

선택 사항. 스키마 마이그레이션이 제대로 적용되었는지 확인할 수 있습니다.
다음 중 하나를 선택할 수 있습니다:
- 마이그레이션 작업의 로그 출력을 검토합니다. 예를 들어:
```
kubectl logs jobs/gitlab-registry-migrations-1
...
OK: applied 154 migrations in 13.752s
```
- 또는, Postgres 데이터베이스에 연결하고 schema_migrations 테이블을 쿼리합니다:
```
SELECT * FROM schema_migrations;
```
  모든 행의 applied_at 열 타임스탬프가 채워져 있는지 확인합니다.

메타데이터 데이터베이스를 사용할 준비가 되었습니다!

기존 레지스트리

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

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

참고:
마이그레이션 프로세스를 자동화하기 위한 작업은 issue 5293에서 추적되고 있습니다.

요구 사항

1단계 또는 3단계 마이그레이션을 시도하기 전에 다음 단계를 완료해야 합니다:

데이터베이스 및 Kubernetes 비밀 만들기.
릴리스를 위한 현재 Helm 값을 가져오고 파일에 저장합니다.
예를 들어, gitlab이라는 이름의 릴리스와 values.yml이라는 이름의 파일에 대해:
```
helm get values gitlab > values.yml
```

1단계 마이그레이션

1단계 마이그레이션을 수행할 때 유의해야 할 점은:

마이그레이션 중 레지스트리는 읽기 전용 모드를 유지해야 합니다.
마이그레이션이 실행 중인 Pod가 종료되면, 프로세스를 완전히 다시 시작해야 합니다. 이 프로세스를 개선하기 위한 작업은 issue 5293에서 추적되고 있습니다.

기존 컨테이너 레지스트리를 메타데이터 데이터베이스로 한 번의 단계로 마이그레이션하려면:

요구 사항 섹션에서 설명한 단계를 따르세요.

values.yml 파일에서 registry: 섹션을 찾아 database 섹션을 추가합니다.
다음과 같이 설정합니다:

database.configure를 true로 설정합니다.
database.enabled를 false로 설정합니다.
maintenance.readonly.enabled를 true로 설정합니다.
migrations.enabled를 true로 설정합니다.

registry:
  enabled: true
  maintenance:
    readonly:
      enabled: true  # 마이그레이션이 실행되는 동안 true로 설정된 상태를 유지해야 함
  database:
    configure: true  # 마이그레이션 단계에서 true여야 함
    enabled: false  # false여야 함!
    name: registry  # 위에서 생성한 데이터베이스 이름과 일치해야 함
    user: registry  # 위에서 생성한 데이터베이스 사용자 이름과 일치해야 함
    password:
      secret: gitlab-registry-database-password  # 비밀 이름과 일치해야 함
      key: password  # 비밀번호를 읽기 위한 비밀 키와 일치해야 함
    sslmode: verify-full  # SSL 연결 모드. https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION에서 더 많은 옵션을 참조하세요.
    ssl:
      secret: gitlab-registry-postgresql-ssl  # 이 비밀을 수동으로 생성해야 함
      clientKey: client-key.pem
      clientCertificate: client-cert.pem
      serverCA: server-ca.pem
    migrations:
      enabled: true  # 이 옵션은 레지스트리 배포의 일환으로 스키마 마이그레이션을 실행합니다

변경 사항을 적용하기 위해 Helm 설치를 업그레이드합니다:
```
helm upgrade gitlab gitlab/gitlab -f values.yml
```
SSH를 통해 레지스트리 포드 중 하나에 연결합니다. 예를 들어 포드 이름이 gitlab-registry-5ddcd9f486-bvb57인 경우:
```
kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash
```

홈 디렉토리로 이동한 다음 다음 명령을 실행합니다:

cd ~
/usr/bin/registry database import /etc/docker/registry/config.yml

명령이 성공적으로 완료되면 모든 이미지가 완전히 가져오기되었습니다.
이제 데이터베이스를 활성화하고 구성에서 읽기 전용 모드를 끌 수 있습니다:

registry:
  enabled: true
  maintenance:
    readonly:
      enabled: false
  database:
    configure: true  # database.enabled가 true로 설정되면 이 옵션을 제거할 수 있습니다
    enabled: true
    name: registry
    user: registry
    password:
      secret: gitlab-registry-database-password
      key: password
    migrations:
      enabled: true

변경 사항을 적용하기 위해 Helm 설치를 다시 업그레이드합니다:
```
helm upgrade gitlab gitlab/gitlab -f values.yml
```

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

세 단계 마이그레이션

기존의 컨테이너 레지스트리 데이터를 메타데이터 데이터베이스로 세 가지 별도의 단계로 마이그레이션할 수 있습니다.

이는 다음과 같은 경우에 권장됩니다:

레지스트리에 데이터가 대량으로 포함되어 있는 경우.
마이그레이션 중 다운타임을 최소화해야 하는 경우.

세 단계로 마이그레이션하려면 다음을 수행해야 합니다:

저장소를 사전 가져오기
모든 저장소 데이터 가져오기
일반 블롭 가져오기

참고: 사용자들은 첫 번째 단계가 시간당 2~4TB의 속도로 완료되었다고 보고했습니다. 느린 속도의 경우, 100TB 이상의 데이터를 가진 레지스트리는 48시간 이상 걸릴 수 있습니다.

단계 1. 저장소를 사전 가져오기

더 큰 인스턴스의 경우, 이 과정은 레지스트리의 크기에 따라 몇 시간 또는 며칠이 걸릴 수 있습니다.

이 프로세스 중에도 레지스트리를 계속 사용할 수 있습니다.

경고: 마이그레이션을 다시 시작하는 것은 아직 가능하지 않습니다

따라서 마이그레이션이 완료되도록 두는 것이 중요합니다.

작업을 중단해야 할 경우, 이 단계를 다시 시작해야 합니다.

요구 사항 섹션에서 설명된 단계를 따르세요.

values.yml 파일의 registry: 섹션을 찾아 database 섹션을 추가합니다. 다음을 설정합니다:

database.configure를 true로 설정합니다.
database.enabled를 false로 설정합니다.
migrations.enabled를 true로 설정합니다.

registry:
  enabled: true
  database:
    configure: true
    enabled: false  # 반드시 false여야 합니다!
    name: registry  # 위에서 생성한 데이터베이스 이름과 일치해야 합니다
    user: registry  # 위에서 생성한 데이터베이스 사용자 이름과 일치해야 합니다
    password:
      secret: gitlab-registry-database-password  # 비밀 이름과 일치해야 합니다
      key: password  # 비밀번호를 읽어오기 위한 비밀 키와 일치해야 합니다
    sslmode: verify-full  # SSL 연결 모드. 추가 옵션은 https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION을 참조하세요.
    ssl:
      secret: gitlab-registry-postgresql-ssl  # 이 비밀은 수동으로 생성해야 합니다
      clientKey: client-key.pem
      clientCertificate: client-cert.pem
      serverCA: server-ca.pem
    migrations:
      enabled: true  # 이 옵션은 레지스트리 배포의 일부로 스키마 마이그레이션을 실행합니다

파일을 저장하고 Helm 설치를 업그레이드하여 배포 변경 사항을 적용합니다:
```
helm upgrade gitlab gitlab/gitlab -f values.yml
```
SSH로 레지스트리 포드 중 하나에 연결합니다. 예를 들어, gitlab-registry-5ddcd9f486-bvb57라는 포드의 경우:
```
kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash
```

홈 디렉토리로 이동한 후 다음 명령을 실행합니다:

cd ~
/usr/bin/registry database import --step-one /etc/docker/registry/config.yml

registry import complete가 표시되면 첫 번째 단계가 완료됩니다.

참고: 다운타임을 줄이기 위해 가능한 한 빨리 다음 단계를 예약해야 합니다. 이상적으로는 첫 번째 단계가 완료된 후 일주일 이내에 진행해야 합니다.

다음 단계 전에 레지스트리에 기록된 새로운 데이터는 해당 단계가 더 오랜 시간이 걸리게 만듭니다.

Step 2. 모든 저장소 데이터 가져오기

이 단계에서는 레지스트리를 읽기 전용 모드로 설정해야 합니다.

이 과정에서 다운타임을 충분히 허용하세요.

values.yml 파일에서 레지스트리를 읽기 전용 모드로 설정합니다:

registry:
  enabled: true
  maintenance:
    readonly:
      enabled: true   # true여야 합니다!
  database:
    configure: true
    enabled: false  # false여야 합니다!
    name: registry  # 위에서 생성한 데이터베이스 이름과 일치해야 합니다
    user: registry  # 위에서 생성한 데이터베이스 사용자 이름과 일치해야 합니다
    password:
      secret: gitlab-registry-database-password  # 비밀 이름과 일치해야 합니다
      key: password  # 비밀번호를 읽기 위한 비밀 키와 일치해야 합니다
    sslmode: verify-full  # SSL 연결 모드. 자세한 내용은 https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION에서 확인하세요.
    ssl:
      secret: gitlab-registry-postgresql-ssl  # 이 비밀을 수동으로 생성해야 합니다
      clientKey: client-key.pem
      clientCertificate: client-cert.pem
      serverCA: server-ca.pem
    migrations:
      enabled: true  # 이 옵션은 레지스트리 배포의 일환으로 스키마 마이그레이션을 실행합니다

파일을 저장하고 Helm 설치를 업그레이드하여 배포에 변경 사항을 적용합니다:
```
helm upgrade gitlab gitlab/gitlab -f values.yml
```
SSH로 레지스트리 포드 중 하나에 연결합니다. 예를 들어, gitlab-registry-5ddcd9f486-bvb57라는 포드에 대해:
```
kubectl exec -ti gitlab-registry-5ddcd9f486-bvb57 bash
```

홈 디렉터리로 변경한 다음, 다음 명령을 실행합니다:

cd ~
/usr/bin/registry database import --step-two /etc/docker/registry/config.yml

명령이 성공적으로 완료되면 모든 이미지가 이제 완전히 가져와졌습니다. 이제 데이터베이스를 활성화하고 구성에서 읽기 전용 모드를 끌 수 있습니다:

registry:
  enabled: true
  maintenance:        # 이 섹션은 제거할 수 있습니다
    readonly:
      enabled: false
  database:
    configure: true  # database.enabled가 true로 설정되면 이 옵션은 제거할 수 있습니다
    enabled: true   # true여야 합니다!
    name: registry  # 위에서 생성한 데이터베이스 이름과 일치해야 합니다
    user: registry  # 위에서 생성한 데이터베이스 사용자 이름과 일치해야 합니다
    password:
      secret: gitlab-registry-database-password  # 비밀 이름과 일치해야 합니다
      key: password  # 비밀번호를 읽기 위한 비밀 키와 일치해야 합니다
    sslmode: verify-full  # SSL 연결 모드. 자세한 내용은 https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION에서 확인하세요.
    ssl:
      secret: gitlab-registry-postgresql-ssl  # 이 비밀을 수동으로 생성해야 합니다
      clientKey: client-key.pem
      clientCertificate: client-cert.pem
      serverCA: server-ca.pem
    migrations:
      enabled: true  # 이 옵션은 레지스트리 배포의 일환으로 스키마 마이그레이션을 실행합니다

파일을 저장하고 Helm 설치를 업그레이드하여 배포에 변경 사항을 적용합니다:
```
helm upgrade gitlab gitlab/gitlab -f values.yml
```

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

3단계. 공통 블롭 가져오기

레지스트리는 현재 메타데이터에 대해 데이터베이스를 완전히 사용하고 있지만,

아직 사용되지 않을 수 있는 레이어 블롭에는 접근할 수 없습니다.

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

cd ~
/usr/bin/registry database import --step-three /etc/docker/registry/config.yml

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

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

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

데이터베이스 생성

Helm 차트 설치를 위한 메타데이터 데이터베이스 활성화

시작하기 전에

새 설치

기존 레지스트리

요구 사항

1단계 마이그레이션

세 단계 마이그레이션

단계 1. 저장소를 사전 가져오기

Step 2. 모든 저장소 데이터 가져오기

3단계. 공통 블롭 가져오기

도움말

기능 사용 가능성과 제품 평가판

도움받기