• 컨테이너 레지스트리 활성화
  • 리눅스 패키지 설치
  • Helm Charts 설치
  • 직접 컴파일한 설치
• 컨테이너 레지스트리 도메인 구성
  • 기존 GitLab 도메인 아래 컨테이너 레지스트리 구성
  • 자신의 도메인에서 컨테이너 레지스트리 구성
• 컨테이너 레지스트리 전체 비활성화
• 새 프로젝트에 대한 컨테이너 레지스트리 비활성화
  • 토큰 기간 늘리기
• 컨테이너 레지스트리의 저장소 구성
  • 파일 시스템 사용
  • 객체 스토리지 사용
    • 리눅스 패키지 설치를 위한 s3 및 gcs 저장 드라이버 구성
    • 자체 컴파일 설치
    • 다운타임 없이 객체 스토리지로 마이그레이션
    • Azure Object Storage로 이동
  • 스토리지 드라이버에 대한 리디렉션 비활성화
    • 암호화된 S3 버킷
  • 저장 한계
• 레지스트리의 내부 포트 변경
• 프로젝트당 컨테이너 레지스트리 비활성화
• GitLab을 인증 엔드포인트로 사용하는 외부 컨테이너 레지스트리
  • Linux 패키지 설치
  • 독립적으로 컴파일한 설치
• 컨테이너 레지스트리 알림 구성
• 지금 클린업 정책 실행
  • 프로젝트별 레지스트리 디스크 용량 사용량
• 컨테이너 레지스트리 메타데이터 데이터베이스
• 컨테이너 레지스트리 가비지 수집
  • 내용 기반 레이어 이해하기
  • 참조되지 않은 레이어 제거하기
  • 태그가 없는 매니페스트 및 참조되지 않은 레이어 제거하기
  • 다운타임 없이 가비지 수집 수행하기
  • 정기적으로 가비지 수집 실행하기
  • 가비지 수집 중지하기
  • 지속적인 무중단 가비지 수집
• GitLab과 레지스트리를 별도의 노드에서 실행하도록 구성하기 (리눅스 패키지 설치)
  • 레지스트리 구성하기
  • GitLab 구성
• GitLab 컨테이너 레지스트리 아키텍처
  • GitLab과 레지스트리 간의 통신
• 타사 레지스트리에서 마이그레이션
  • 도커 배포 레지스트리

GitLab 컨테이너 레지스트리 관리

GitLab 컨테이너 레지스트리를 사용하면 모든 프로젝트가 Docker 이미지를 저장할 수 있는 자체 공간을 가질 수 있습니다.

배포 레지스트리에 대한 더 많은 정보는 다음을 참고하세요:

• 구성
• 저장 드라이버
• 레지스트리 서버 배포

이 문서는 관리자 가이드입니다. GitLab 컨테이너 레지스트리를 사용하는 방법에 대한 내용은 사용자 문서를 참조하세요.

컨테이너 레지스트리 활성화

컨테이너 레지스트리를 활성화하는 과정은 사용 중인 설치 유형에 따라 다릅니다.

리눅스 패키지 설치

Linux 패키지를 사용하여 GitLab을 설치한 경우, 컨테이너 레지스트리는 기본적으로 사용 가능하지 않을 수 있습니다.

내장된 Let’s Encrypt 통합을 사용하는 경우, 컨테이너 레지스트리는 자동으로 활성화되어 귀하의 GitLab 도메인에서 포트 5050으로 사용 가능합니다.

그렇지 않으면, 컨테이너 레지스트리는 활성화되지 않습니다. 활성화하려면:

• 기존 GitLab 도메인에 대한 설정을 구성하거나,
• 다른 도메인에 대한 설정을 구성할 수 있습니다.

컨테이너 레지스트리는 기본적으로 HTTPS에서 작동합니다. HTTP를 사용할 수 있지만 권장되지 않으며 이 문서의 범위를 벗어납니다.

Helm Charts 설치

Helm Charts 설치의 경우 컨테이너 레지스트리 사용하기를 참조하세요.

직접 컴파일한 설치

GitLab 설치를 직접 컴파일한 경우:

1. 설치하려는 GitLab 버전의 이미지에 해당하는 레지스트리를 배포해야 합니다
   (예: registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab)
2. 설치가 완료된 후 활성화하려면 gitlab.yml에서 레지스트리의 설정을 구성해야 합니다.
3. lib/support/nginx/registry-ssl 아래의 샘플 NGINX 구성 파일을 사용하고 host, port, 및 TLS 인증서 경로에 맞게 편집하세요.

gitlab.yml의 내용은 다음과 같습니다:

registry:
  enabled: true
  host: registry.gitlab.example.com
  port: 5005
  api_url: http://localhost:5000/
  key: config/registry.key
  path: shared/registry
  issuer: gitlab-issuer

여기서:

소스에서 설치한 경우 GitLab과 함께 레지스트리 초기 파일이 제공되지 않습니다.
따라서 설정을 수정하는 경우 GitLab 다시 시작하기는 레지스트리를 재시작하지 않습니다. 이를 수행하는 방법에 대한 상위 문서를 참조하세요.

절대적으로 최소한으로, 레지스트리 구성에 container_registry를 서비스로 설정하고 https://gitlab.example.com/jwt/auth를 영역으로 설정해야 합니다:

auth:
  token:
    realm: https://gitlab.example.com/jwt/auth
    service: container_registry
    issuer: gitlab-issuer
    rootcertbundle: /root/certs/certbundle

컨테이너 레지스트리 도메인 구성

Registry의 외부 도메인은 다음 두 가지 방법 중 하나로 구성할 수 있습니다:

• 기존 GitLab 도메인 사용하기.
  Registry는 포트를 통해 수신 대기하고 GitLab에서 TLS 인증서를 재사용합니다.

• 완전히 별도의 도메인 사용하기
  해당 도메인에 대한 새로운 TLS 인증서가 필요합니다.

컨테이너 레지스트리가 TLS 인증서를 필요로 하기 때문에 비용이 중요한 요소가 될 수 있습니다.

컨테이너 레지스트리를 처음 구성하기 전에 이 점을 고려하세요.

기존 GitLab 도메인 아래 컨테이너 레지스트리 구성

컨테이너 레지스트리가 기존 GitLab 도메인을 사용하도록 구성되면
포트를 통해 컨테이너 레지스트리를 노출할 수 있습니다. 이렇게 하면 기존의 GitLab TLS 인증서를 재사용할 수 있습니다.

GitLab 도메인이 https://gitlab.example.com이고 외부 세계에 대한 포트가 5050일 경우,
컨테이너 레지스트리를 구성하려면:

• 리눅스 패키지 설치를 사용하는 경우 gitlab.rb를 편집합니다.
• 소스에서 컴파일한 설치를 사용하는 경우 gitlab.yml을 편집합니다.

Registry가 수신 대기하는 포트(기본값은 5000)와 다른 포트를 선택해야
충돌이 발생하지 않습니다.

참고: 호스트 및 컨테이너 방화벽 규칙이 gitlab_rails['registry_port'](기본값 5000) 아래에 나열된 포트가 아니라
registry_external_url 행 아래에 나열된 포트를 통해 트래픽을 허용하도록 구성되어야 합니다.

registry_external_url 'https://registry-gitlab.example.com'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678

이제 사용자는 다음을 사용하여 GitLab 자격 증명으로
컨테이너 레지스트리에 로그인할 수 있어야 합니다:

docker login gitlab.example.com:5050

자신의 도메인에서 컨테이너 레지스트리 구성

레지스트리를 자신의 도메인에서 사용하도록 구성할 때, 특정 도메인(예: registry.example.com)에 대한 TLS 인증서가 필요합니다. 기존 GitLab 도메인의 하위 도메인에서 호스팅되는 경우 와일드카드 인증서가 필요할 수 있습니다. 예를 들어, *.gitlab.example.com는 registry.gitlab.example.com과 일치하는 와일드카드이며, *.example.com과는 다릅니다.

수동으로 생성된 SSL 인증서(여기에서 설명)가 있을 뿐만 아니라 Let’s Encrypt에서 자동 생성된 인증서도 Linux 패키지 설치에서 지원됩니다.

컨테이너 레지스트리에 https://registry.gitlab.example.com에서 액세스할 수 있기를 원한다고 가정해 봅시다.

registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"

이제 사용자는 GitLab 자격 증명을 사용하여 컨테이너 레지스트리에 로그인할 수 있어야 합니다:

docker login registry.gitlab.example.com

컨테이너 레지스트리 전체 비활성화

다음 단계를 따라 레지스트리를 비활성화하면 기존 Docker 이미지가 제거되지 않습니다. Docker 이미지 제거는 레지스트리 애플리케이션 자체에서 처리됩니다.

새 프로젝트에 대한 컨테이너 레지스트리 비활성화

컨테이너 레지스트리가 활성화된 경우 모든 새 프로젝트에서 사용할 수 있어야 합니다. 이 기능을 비활성화하고 프로젝트 소유자가 컨테이너 레지스트리를 직접 활성화할 수 있도록 하려면 아래 단계를 따르세요.

토큰 기간 늘리기

GitLab에서 컨테이너 레지스트리의 토큰은 매 5분마다 만료됩니다.

토큰 기간을 늘리려면:

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
2. Settings > CI/CD를 선택합니다.
3. Container Registry를 확장합니다.
4. Authorization token duration (minutes)의 값을 업데이트합니다.
5. Save changes를 선택합니다.

컨테이너 레지스트리의 저장소 구성

저장소 드라이버를 구성하여 다양한 저장소 백엔드를 사용할 수 있도록 컨테이너 레지스트리를 구성할 수 있습니다. 기본적으로 GitLab 컨테이너 레지스트리는 파일 시스템 드라이버 구성으로 설정되어 있습니다.

지원되는 다양한 드라이버는 다음과 같습니다:

대부분의 S3 호환 서비스(예: MinIO)가 컨테이너 레지스트리와 함께 작동할 것으로 예상되지만, AWS S3에 대해서만 지원을 보장합니다. 타사 S3 구현의 정확성을 보장할 수 없기 때문에, 문제를 디버그할 수는 있지만 AWS S3 버킷에 대해 문제가 재현되지 않는 한 레지스트리를 패치할 수 없습니다.

파일 시스템 사용

이미지를 파일 시스템에 저장하려면, 컨테이너 레지스트리의 저장 경로를 변경할 수 있습니다. 아래 단계를 따릅니다.

이 경로는 다음 사용자에게 접근 가능합니다:

• 컨테이너 레지스트리 데몬을 실행하는 사용자.
• GitLab을 실행하는 사용자.

모든 GitLab, 레지스트리 및 웹 서버 사용자는 이 디렉토리에 접근할 수 있어야 합니다.

객체 스토리지 사용

이미지를 객체 스토리지에 저장하려면, 컨테이너 레지스트리의 저장 드라이버를 변경할 수 있습니다.

GitLab과 함께 객체 스토리지 사용에 대해 더 알아보세요.

경고: GitLab은 파일 시스템에 저장되지 않은 Docker 이미지를 백업하지 않습니다. 원하는 경우 객체 스토리지 공급자와 함께 백업을 활성화하십시오.

리눅스 패키지 설치를 위한 s3 및 gcs 저장 드라이버 구성

다음 구성 단계는 s3 및 gcs 저장 드라이버에 해당합니다. 다른 저장 드라이버도 지원됩니다.

리눅스 패키지 설치에 대해 s3 저장 드라이버를 구성하려면:

1. /etc/gitlab/gitlab.rb 파일을 수정합니다:

   registry['storage'] = {
     's3' => {
       'accesskey' => 's3-access-key',
       'secretkey' => 's3-secret-key-for-access-key',
       'bucket' => 'your-s3-bucket',
       'region' => 'your-s3-region',
       'regionendpoint' => 'your-s3-regionendpoint'
     }
   }
   

   정적 자격 증명의 사용을 피하려면, IAM 역할을 사용하고 accesskey 및 secretkey를 생략합니다. IAM 프로필이 Docker에서 문서화된 권한을 따르는지 확인하십시오.

   registry['storage'] = {
     's3' => {
       'bucket' => 'your-s3-bucket',
       'region' => 'your-s3-region'
     }
   }
   

   AWS S3 VPC 엔드포인트와 함께 사용하는 경우, regionendpoint를 VPC 엔드포인트 주소로 설정하고 pathstyle을 false로 설정합니다:

   registry['storage'] = {
     's3' => {
       'accesskey' => 's3-access-key',
       'secretkey' => 's3-secret-key-for-access-key',
       'bucket' => 'your-s3-bucket',
       'region' => 'your-s3-region',
       'regionendpoint' => 'your-s3-vpc-endpoint',
       'pathstyle' => false
     }
   }
   

   • regionendpoint는 MinIO와 같은 S3 호환 서비스를 구성할 때만 필요하거나 AWS S3 VPC 엔드포인트를 사용할 때 필요합니다.
   • your-s3-bucket은 존재하는 버킷의 이름이어야 하며, 하위 디렉토리를 포함할 수 없습니다.
   • pathstyle은 bucket_name.host/object 대신 host/bucket_name/object 스타일 경로를 사용하려면 true로 설정해야 합니다. AWS S3의 경우 false로 설정합니다.

   S3에 대한 연결에 대한 속도 제한을 설정하여 S3 API의 503 오류를 방지할 수 있습니다. 이를 위해, maxrequestspersecond를 S3 요청 속도 임계값 내의 숫자로 설정합니다:

   registry['storage'] = {
     's3' => {
       'accesskey' => 's3-access-key',
       'secretkey' => 's3-secret-key-for-access-key',
       'bucket' => 'your-s3-bucket',
       'region' => 'your-s3-region',
       'regionendpoint' => 'your-s3-regionendpoint',
       'maxrequestspersecond' => 100
     }
   }
   

2. 파일을 저장하고 GitLab 재구성하기를 통해 변경 사항이 적용되도록 합니다.

리눅스 패키지 설치에 대해 gcs 저장 드라이버를 구성하려면:

1. /etc/gitlab/gitlab.rb 파일을 수정합니다:

   registry['storage'] = {
     'gcs' => {
       'bucket' => 'BUCKET_NAME',
       'keyfile' => 'PATH/TO/KEYFILE',
       # 레지스트리 외부의 다른 앱과 공유되는 버킷이 있는 경우, 
       # 아래 주석을 해제하세요:
       # 'rootdirectory' => '/gcs/object/name/prefix'
     }
   }
   

   GitLab은 모든 사용 가능한 매개변수를 지원합니다.

2. 파일을 저장하고 GitLab 재구성하기를 통해 변경 사항이 적용되도록 합니다.

자체 컴파일 설치

스토리지 드라이버 구성은 Docker 레지스트리를 배포할 때 생성된 레지스트리 구성 YAML 파일에서 수행됩니다.

s3 스토리지 드라이버 예시:

storage:
  s3:
    accesskey: 's3-access-key'                # IAM 역할을 사용하는 경우 필요 없음
    secretkey: 's3-secret-key-for-access-key' # IAM 역할을 사용하는 경우 필요 없음
    bucket: 'your-s3-bucket'
    region: 'your-s3-region'
    regionendpoint: 'your-s3-regionendpoint'
  cache:
    blobdescriptor: inmemory
  delete:
    enabled: true

your-s3-bucket은 존재하는 버킷의 이름이어야 하며, 하위 디렉터리를 포함할 수 없습니다.

다운타임 없이 객체 스토리지로 마이그레이션

경고:

AWS DataSync를 사용하여 레지스트리 데이터를 S3 버킷으로 복사하면 버킷에 잘못된 메타데이터 객체가 생성됩니다.

추가 세부사항은 빈 이름이 있는 태그를 참조하세요.

S3 버킷 간에 데이터를 이동하려면 AWS CLI sync 작업을 권장합니다.

컨테이너 레지스트리를 중지하지 않고 스토리지를 마이그레이션하려면 컨테이너 레지스트리를 읽기 전용 모드로 설정하세요. 대형 인스턴스의 경우, 컨테이너 레지스트리가 읽기 전용 모드로 유지되어야 할 수 있습니다. 이 시간 동안 컨테이너 레지스트리에서 이미지를 당길 수 있지만, 이미지를 밀어넣을 수는 없습니다.

1. 선택 사항: 마이그레이션할 데이터 양을 줄이려면 다운타임 없이 가비지 수집 도구를 실행하세요.

2. 이 예에서는 aws CLI를 사용합니다. CLI를 구성하지 않았다면 sudo aws configure를 실행하여 자격 증명을 구성해야 합니다. 비관리자 사용자는 컨테이너 레지스트리 폴더에 접근할 수 없을 가능성이 높으므로 sudo를 사용해야 합니다. 자격 증명 구성을 확인하려면 ls를 실행하여 모든 버킷을 나열하세요.

   sudo aws --endpoint-url https://your-object-storage-backend.com s3 ls
   

   AWS를 백엔드로 사용하는 경우 --endpoint-url가 필요하지 않습니다.

3. 초기 데이터를 S3 버킷으로 복사합니다. 예를 들어 aws CLI의 cp 또는 sync 명령어를 사용합니다. 버킷 내에서 docker 폴더를 최상위 폴더로 유지하는 것을 잊지 마세요.

   sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket
   

   참고: 데이터가 많은 경우 병렬 동기화 작업을 실행하여 성능을 개선할 수 있습니다.

4. 최종 데이터 동기화를 수행하려면 컨테이너 레지스트리를 read-only 모드로 설정하고 GitLab을 재구성하세요.

5. 초기 데이터 로드 이후의 변경 사항을 S3 버킷에 동기화하고, 대상 버킷에는 있지만 소스에는 없는 파일을 삭제하세요:

   sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket --delete --dryrun
   

   명령이 예상대로 수행되는지 확인한 후 --dryrun 플래그를 제거하고 명령을 실행하세요.

   경고: --delete 플래그는 대상에 존재하지만 소스에 없는 파일을 삭제합니다. 소스와 대상을 바꾸면 레지스트리의 모든 데이터가 삭제됩니다.

6. 다음 두 명령어의 반환된 파일 수를 확인하여 모든 컨테이너 레지스트리 파일이 객체 스토리지에 업로드되었는지 확인하세요:

   sudo find registry -type f | wc -l
   

   sudo aws --endpoint-url https://your-object-storage-backend.com s3 ls s3://mybucket --recursive | wc -l
   

   이 명령어 출력은 _uploads 디렉터리와 하위 디렉터리의 내용을 제외하고 일치해야 합니다.

7. 레지스트리를 S3 버킷을 사용하여 저장하도록 구성하세요.

8. 변경 사항이 적용되려면 Registry를 다시 read-write 모드로 설정하고 GitLab을 재구성하세요.

Azure Object Storage로 이동

registry['storage'] = {
  'azure' => {
    'accountname' => '<your_storage_account_name>',
    'accountkey' => '<base64_encoded_account_key>',
    'container' => '<container_name>',
    'trimlegacyrootprefix' => true
  }
}

storage:
  azure:
    accountname: <your_storage_account_name>
    accountkey: <base64_encoded_account_key>
    container: <container_name>
    trimlegacyrootprefix: true

기본적으로 Azure Storage Driver는 core.windows.net 영역을 사용합니다. azure 섹션에서 realm에 대해 다른 값을 설정할 수 있습니다 (예: Azure 정부 클라우드의 경우 core.usgovcloudapi.net).

스토리지 드라이버에 대한 리디렉션 비활성화

기본적으로 원격 백엔드로 구성된 레지스트리에 접근하는 사용자는 스토리지 드라이버의 기본 백엔드로 리디렉션됩니다. 예를 들어, 레지스트리는 s3 스토리지 드라이버를 사용하여 구성될 수 있으며, 이는 GitLab 서버의 부하를 완화하기 위해 원격 S3 버킷으로 요청을 리디렉션합니다.

그러나 이 동작은 일반적으로 공개 서버에 접근할 수 없는 내부 호스트에서 사용되는 레지스트리에는 바람직하지 않습니다. 리디렉션을 비활성화하려면 프록시 다운로드 설정에서 disable 플래그를 true로 설정하세요. 이렇게 하면 모든 트래픽이 항상 레지스트리 서비스를 통해 이동하게 됩니다. 이는 보안을 개선하고(스토리지 백엔드가 공개에 액세스할 수 없도록 하여 공격 표면을 줄임), 그러나 성능은 저하됩니다(모든 트래픽이 서비스를 통해 리디렉션됩니다).

암호화된 S3 버킷

S3 버킷에 대해 AWS KMS를 사용한 서버 측 암호화를 사용하여 기본적으로 SSE-S3 또는 SSE-KMS 암호화가 활성화된 버킷을 사용할 수 있습니다.

사용자 마스터 키(CMK) 및 SSE-C 암호화는 지원되지 않습니다. 이는 모든 요청에 암호화 키를 전송해야 하기 때문입니다.

SSE-S3의 경우, 레지스트리 설정에서 encrypt 옵션을 활성화해야 합니다. 이렇게 하는 방법은 GitLab을 설치한 방법에 따라 다릅니다. 설치 방법에 맞는 지침을 따르세요.

저장 한계

저장 한계가 없으므로 사용자는 임의의 크기로 무한량의 Docker 이미지를 업로드할 수 있습니다. 이 설정은 향후 릴리스에서 구성 가능해야 합니다.

레지스트리의 내부 포트 변경

레지스트리 서버는 기본적으로 포트 5000에서 localhost를 수신 대기하며, 이는 레지스트리 서버가 연결을 수락해야 할 주소입니다. 아래 예제에서는 레지스트리의 포트를 5010으로 설정합니다.

프로젝트당 컨테이너 레지스트리 비활성화

귀하의 GitLab 인스턴스에서 레지스트리가 활성화되어 있지만 프로젝트에 필요하지 않은 경우, 프로젝트의 설정에서 비활성화할 수 있습니다.

GitLab을 인증 엔드포인트로 사용하는 외부 컨테이너 레지스트리

경고:
GitLab에서 서드파티 컨테이너 레지스트리를 사용하는 것은 사용 중단되었으며 GitLab 15.8에서 지원이 종료되었습니다.
서드파티 컨테이너 레지스트리를 사용해야 하는 경우, 피드백 이슈 958에서 사용 사례를 알려주세요.

외부 컨테이너 레지스트리를 사용하는 경우, 컨테이너 레지스트리와 관련된 일부 기능이 사용할 수 없거나 고유한 위험을 가질 수 있습니다.

통합이 작동하려면 외부 레지스트리가 GitLab과 인증하는 데 JSON 웹 토큰을 사용하도록 구성되어 있어야 합니다.
외부 레지스트리의 런타임 구성 must 다음 항목을 포함해야 합니다:

auth:
  token:
    realm: https://gitlab.example.com/jwt/auth
    service: container_registry
    issuer: gitlab-issuer
    rootcertbundle: /root/certs/certbundle

이 항목이 없으면 레지스트리 로그인이 GitLab과 인증될 수 없습니다. GitLab은 또한
프로젝트 계층 아래의 중첩 이미지 이름에 대해 인식하지 못하며,
registry.example.com/group/project/image-name:tag 또는
registry.example.com/group/project/my/image-name:tag와 같은 형태로만 인식합니다.

Linux 패키지 설치

GitLab을 인증 엔드포인트로 사용하여 외부 컨테이너 레지스트리를 사용할 수 있습니다.

1. /etc/gitlab/gitlab.rb를 열고 필요한 구성을 설정합니다:

   gitlab_rails['registry_enabled'] = true
   gitlab_rails['registry_api_url'] = "https://<external_registry_host>:5000"
   gitlab_rails['registry_issuer'] = "gitlab-issuer"
   

   • gitlab_rails['registry_enabled'] = true는 GitLab 컨테이너 레지스트리 기능 및 인증 엔드포인트를 활성화하는 데 필요합니다. 이 것이 활성화되어도 GitLab 번들 컨테이너 레지스트리 서비스는 시작되지 않습니다.
   • gitlab_rails['registry_api_url'] = "http://<external_registry_host>:5000"는 레지스트리가 설치된 호스트와 일치하도록 변경해야 합니다.
     TLS를 사용하도록 외부 레지스트리가 구성된 경우 https를 지정해야 합니다.

2. GitLab과 외부 컨테이너 레지스트리가 안전하게 통신하기 위해서는 인증서-키 쌍이 필요합니다.
   인증서-키 쌍을 생성하고 외부 컨테이너 레지스트리를 공개 인증서(rootcertbundle)로 구성하고,
   GitLab은 개인 키로 구성해야 합니다.
   이를 위해 /etc/gitlab/gitlab.rb에 다음을 추가합니다:

   # registry['internal_key']는 사용자 정의 키 파일의 내용을 포함해야 합니다.
   # 키 파일의 줄 바꿈은 `\n` 문자로 표시해야 합니다
   # 예시:
   registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
   
   # 선택적으로, Linux 패키지 설치를 위해 registry['internal_key'] 내용을 작성할 맞춤 파일을 정의할 수 있습니다.
   gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
   

   재구성이 실행될 때마다 registry_key_path에 지정된 파일이 internal_key에 의해 지정된 내용으로 채워집니다.
   파일이 지정되지 않은 경우, Linux 패키지 설치는 기본적으로 /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key에 채워집니다.

3. GitLab 컨테이너 레지스트리 페이지에 표시되는 컨테이너 레지스트리 URL을 변경하려면 다음 구성을 설정하십시오:

   gitlab_rails['registry_host'] = "registry.gitlab.example.com"
   gitlab_rails['registry_port'] = "5005"
   

4. 파일을 저장하고 GitLab 재구성하여 변경 사항이 적용되도록 합니다.

독립적으로 컴파일한 설치

1. /home/git/gitlab/config/gitlab.yml를 열고 registry 아래의 구성 설정을 수정합니다:

   ## 컨테이너 레지스트리
   
   registry:
     enabled: true
     host: "registry.gitlab.example.com"
     port: "5005"
     api_url: "https://<external_registry_host>:5000"
     path: /var/lib/registry
     key: /path/to/keyfile
     issuer: gitlab-issuer
   

   이러한 매개변수의 의미에 대해 더 알아보기.

2. 파일을 저장하고 GitLab을 재시작하여 변경 사항이 적용되도록 합니다.

컨테이너 레지스트리 알림 구성

컨테이너 레지스트리를 구성하여 레지스트리에서 발생하는 이벤트에 대한 웹훅 알림을 보낼 수 있습니다.

Docker 레지스트리 알림 문서에서 컨테이너 레지스트리 알림 구성 옵션에 대해 더 알아보세요.

경고: threshold 매개변수에 대한 지원은 GitLab 17.0에서 사용 중지 되었으며, 18.0에서 제거될 예정입니다. 대신 maxretries를 사용하세요.

컨테이너 레지스트리에 대해 여러 엔드포인트를 구성할 수 있습니다.

notifications:
  endpoints:
    - name: alistener
      disabled: false
      url: https://my.listener.com/event
      headers: <http.Header>
      timeout: 500
      threshold: 5 # 사용 중지됨: 대신 `maxretries`를 사용하세요.
      maxretries: 5
      backoff: 1000

지금 클린업 정책 실행

경고: 분산 아키텍처를 사용하고 Sidekiq가 다른 노드에서 실행되고 있는 경우, 클린업 정책이 작동하지 않습니다. 이를 해결하기 위해:

1. Sidekiq 노드의 gitlab.rb 파일을 수정하여 올바른 레지스트리 URL을 가리키도록 합니다.
2. registry.key 파일을 각 Sidekiq 노드에 복사합니다.

자세한 내용은 Sidekiq 구성 페이지를 참조하세요.

주어진 프로젝트에 의해 사용되는 컨테이너 레지스트리 디스크 공간의 양을 줄이기 위해, 관리자는 클린업 정책을 설정하고 가비지 수집을 실행할 수 있습니다.

프로젝트별 레지스트리 디스크 용량 사용량

각 프로젝트에서 사용되는 디스크 공간을 찾으려면 다음을 실행하세요.

GitLab Rails 콘솔:

projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]]
# 확인하고자 하는 프로젝트를 지정해야 합니다. 이를 다양한 방법으로 가져올 수 있습니다.
projects = Project.last(100)

projects.each do |p|
   project_total_size = 0
   container_repositories = p.container_repositories

   container_repositories.each do |c|
       c.tags.each do |t|
          project_total_size = project_total_size + t.total_size unless t.total_size.nil?
       end
   end

   if project_total_size > 0
      projects_and_size << [p.project_id, p.creator&.id, project_total_size, p.full_path]
   end
end

# 쉼표로 구분된 출력으로 인쇄합니다.
projects_and_size.each do |ps|
   puts "%s,%s,%s,%s" % ps
end

이미지 태그를 제거하려면 정리 정책을 실행하세요. 다음 명령을 실행합니다.

GitLab Rails 콘솔:

# 정리할 컨테이너 레지스트리의 프로젝트의 숫자 ID
P = <project_id>

# 프로젝트에 대해 개발자, 유지 관리자 또는 소유자 역할을 가진 사용자의 숫자 ID
U = <user_id>

# 필요한 세부정보/객체 가져오기
user    = User.find_by_id(U)
project = Project.find_by_id(P)
policy  = ContainerExpirationPolicy.find_by(project_id: P)

# 각 컨테이너 레포지토리 루프
project.container_repositories.find_each do |repo|
  puts repo.attributes

  # 태그 정리 시작
  puts Projects::ContainerRepository::CleanupTagsService.new(container_repository: repo, current_user: user, params: policy.attributes.except("created_at", "updated_at")).execute
end

계획에 따라 정리 실행도 가능합니다.

모든 프로젝트 인스턴스에서 정리 정책을 활성화하려면 컨테이너 레지스트리가 있는 모든 프로젝트를 찾아야 하지만 정리 정책이 비활성화된 상태여야 합니다.

# 컨테이너 레지스트리가 활성화되고 정리 정책이 비활성화된 모든 프로젝트 찾기

projects = Project.find_by_sql ("SELECT * FROM projects WHERE id IN (SELECT project_id FROM container_expiration_policies WHERE enabled=false AND id IN (SELECT project_id FROM container_repositories))")

# 각 프로젝트 루프
projects.each do |p|

# 프로젝트 ID 및 프로젝트 전체 이름 인쇄
    puts "#{p.id},#{p.full_name}"
end

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

Offering: Self-managed

• GitLab 17.3에서 일반적으로 사용 가능.

메타데이터 데이터베이스는 온라인 가비지 수집을 포함하여 많은 새로운 레지스트리 기능을 가능하게 하며, 많은 레지스트리 작업의 효율성을 증가시킵니다.

자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스 페이지를 참조하세요.

컨테이너 레지스트리 가비지 수집

컨테이너 레지스트리는 상당한 양의 저장공간을 사용할 수 있으며, 저장소 사용량 줄이기를 원할 수 있습니다.

나열된 옵션 중에서 태그 삭제가 가장 효과적인 옵션입니다. 그러나 태그 삭제만으로는 이미지 레이어가 삭제되지 않고, 단지 기본 이미지 매니페스트가 태그가 없는 상태로 남게 됩니다.

공간을 보다 효과적으로 확보하기 위해, 컨테이너 레지스트리에는 참조되지 않은 레이어와 (선택적으로) 태그가 없는 매니페스트를 삭제할 수 있는 가비지 수집기가 있습니다.

가비지 수집기를 시작하려면 gitlab-ctl에서 제공하는 registry-garbage-collect 명령을 사용하세요.

이 명령은 가비지 수집 전에 컨테이너 레지스트리를 종료하고, 가비지 수집이 완료된 후에 다시 시작합니다. 다운타임을 피하려면 컨테이너 레지스트리를 읽기 전용 모드로 설정하고 gitlab-ctl을 우회하세요.

가비지 수집을 수행하는 데 필요한 시간은 컨테이너 레지스트리 데이터 크기에 비례합니다.

필수 조건:

• Linux 패키지 또는 GitLab Helm 차트를 사용하여 GitLab을 설치해야 합니다.

내용 기반 레이어 이해하기

다음 예를 고려해보세요. 먼저 이미지를 빌드합니다:

# sha256:111111의 내용을 가진 이미지를 빌드합니다
docker build -t my.registry.com/my.group/my.project:latest .
docker push my.registry.com/my.group/my.project:latest

이제 새로운 버전으로 :latest를 덮어씁니다:

# sha256:222222의 내용을 가진 이미지를 빌드합니다
docker build -t my.registry.com/my.group/my.project:latest .
docker push my.registry.com/my.group/my.project:latest

이제 :latest 태그는 sha256:222222의 매니페스트를 가리킵니다.

레지스트리 아키텍처 덕분에 이 데이터는 여전히 my.registry.com/my.group/my.project@sha256:111111 이미지를 풀 때 접근할 수 있지만, 더 이상 :latest 태그를 통해 직접 접근할 수 없습니다.

참조되지 않은 레이어 제거하기

이미지 레이어는 컨테이너 레지스트리 저장소의 대부분을 차지합니다. 레이어가 참조되지 않았다고 간주되려면 어떤 이미지 매니페스트에서도 이를 참조하지 않아야 합니다. 참조되지 않은 레이어는 컨테이너 레지스트리 가비지 수집기의 기본 대상입니다.

구성 파일의 기본 위치를 변경하지 않았다면, 다음을 실행합니다:

sudo gitlab-ctl registry-garbage-collect

컨테이너 레지스트리 config.yml의 위치를 변경했다면:

sudo gitlab-ctl registry-garbage-collect /path/to/config.yml

또한 추가 공간을 확보하기 위해 모든 태그가 없는 매니페스트 및 참조되지 않은 레이어를 제거할 수 있습니다.

태그가 없는 매니페스트 및 참조되지 않은 레이어 제거하기

기본적으로 컨테이너 레지스트리 가비지 수집기는 태그가 없는 이미지를 무시하며, 사용자는 다이제스트로 태그가 없는 이미지를 계속 가져올 수 있습니다. 사용자는 앞으로 이미지를 재 태그하여 GitLab UI 및 API에서 다시 볼 수 있게 만들 수 있습니다.

태그가 없는 이미지와 이러한 이미지에 의해 독점적으로 참조되는 레이어에 대해 신경 쓰지 않는 경우, 모두 삭제할 수 있습니다. registry-garbage-collect 명령어에 -m 플래그를 사용하세요:

sudo gitlab-ctl registry-garbage-collect -m

태그가 없는 이미지를 삭제하는 것에 대해 확신이 없다면, 진행하기 전에 레지스트리 데이터를 백업하세요.

다운타임 없이 가비지 수집 수행하기

컨테이너 레지스트리를 온라인 상태로 유지하면서 가비지 수집을 수행하려면, 레지스트리를 읽기 전용 모드로 설정하고 내장된 gitlab-ctl registry-garbage-collect 명령어를 우회하세요.

컨테이너 레지스트리가 읽기 전용 모드일 때 이미지를 풀 수는 있지만 푸시할 수는 없습니다. 컨테이너 레지스트리는 가비지 수집이 완료될 때까지 전체 기간 동안 읽기 전용 상태를 유지해야 합니다.

기본적으로 레지스트리 저장소 경로는 /var/opt/gitlab/gitlab-rails/shared/registry입니다.

읽기 전용 모드를 활성화하려면:

1. /etc/gitlab/gitlab.rb에서 읽기 전용 모드를 지정합니다:

   registry['storage'] = {
     'filesystem' => {
       'rootdirectory' => "<your_registry_storage_path>"
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => true
       }
     }
   }
   

2. GitLab을 저장하고 재구성합니다:

   sudo gitlab-ctl reconfigure
   

   이 명령은 컨테이너 레지스트리를 읽기 전용 모드로 설정합니다.

3. 다음으로, 가비지 수집 명령 중 하나를 트리거합니다:

   # 참조되지 않은 레이어 제거
   sudo /opt/gitlab/embedded/bin/registry garbage-collect /var/opt/gitlab/registry/config.yml
   
   # 태그가 없는 매니페스트 및 참조되지 않은 레이어 제거
   sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml
   

   이 명령은 가비지 수집을 시작합니다. 완료하는 데 걸리는 시간은 레지스트리 데이터 크기에 비례합니다.

4. 작업이 완료되면, /etc/gitlab/gitlab.rb에서 다시 읽기/쓰기 모드로 변경합니다:

   registry['storage'] = {
     'filesystem' => {
       'rootdirectory' => "<your_registry_storage_path>"
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => false
       }
     }
   }
   

5. GitLab을 저장하고 재구성합니다:

   sudo gitlab-ctl reconfigure
   

정기적으로 가비지 수집 실행하기

이상적으로는 레지스트리의 가비지 수집을 정기적으로, 사용 중이지 않은 시간에 매주 실행하고자 합니다.

가장 간단한 방법은 매주 주기적으로 실행되는 새 crontab 작업을 추가하는 것입니다.

/etc/cron.d/registry-garbage-collect 아래에 파일을 생성하세요:

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

# 매주 일요일 오전 04:05에 실행
5 4 * * 0  root gitlab-ctl registry-garbage-collect

-m 플래그를 추가하여 태그 없는 매니페스트 및 참조되지 않은 레이어를 제거하는 것도 고려할 수 있습니다.

가비지 수집 중지하기

가비지 수집을 중지할 계획이 있는 경우, 다운타임 없이 가비지 수집 수행하기에서 설명한 대로 수동으로 가비지 수집을 실행해야 합니다.

그런 다음 Control+C를 눌러 가비지 수집을 중지할 수 있습니다.

그렇지 않으면 gitlab-ctl을 중단하면 레지스트리 서비스가 중단 상태가 될 수 있습니다.

이 경우 gitlab-ctl 명령이 레지스트리 서비스를 다시 시작할 수 있도록 시스템에서 가비지 수집 프로세스를 찾아야 합니다.

또한, 프로세스의 마크 단계 동안 진행 상황이나 결과를 저장할 방법이 없습니다.

블롭이 삭제되기 시작해야만 영구적으로 수행됩니다.

지속적인 무중단 가비지 수집

메타데이터 데이터베이스로 마이그레이션하면 가비지 수집을 백그라운드에서 실행할 수 있으며, 이를 위해 스케줄링하거나 읽기 전용 모드가 필요하지 않습니다.

GitLab과 레지스트리를 별도의 노드에서 실행하도록 구성하기 (리눅스 패키지 설치)

기본적으로 패키지는 두 서비스가 같은 노드에서 실행되고 있다고 가정합니다.

GitLab과 레지스트리를 별도의 노드에서 실행하려면 레지스트리와 GitLab에 대해 별도의 구성이 필요합니다.

레지스트리 구성하기

레지스트리가 GitLab과 분리되어 실행되도록 하기 위해 /etc/gitlab/gitlab.rb에서 설정해야 할 구성 옵션은 다음과 같습니다:

• registry['registry_http_addr'], 기본적으로 프로그래밍 방식으로 설정됨. 웹 서버(또는 LB)에서 접근 가능해야 합니다.
• registry['token_realm'], 기본적으로 프로그래밍 방식으로 설정됨. 인증을 수행하기 위해 사용할 엔드포인트를 지정하며, 일반적으로 GitLab URL입니다.

이 엔드포인트는 사용자가 접근할 수 있어야 합니다.

• registry['http_secret'], 무작위 문자열. 변조 방지를 위해 클라이언트와 함께 저장될 수 있는 상태에 서명하는 데 사용되는 무작위 데이터 조각입니다.
• registry['internal_key'], 기본적으로 자동으로 생성됨. GitLab이 토큰에 서명하는 데 사용하는 키의 내용입니다. 키는 레지스트리 서버에서 생성되지만 그곳에서는 사용되지 않습니다.
• gitlab_rails['registry_key_path'], 기본적으로 프로그래밍 방식으로 설정됨. internal_key의 내용이 디스크에 기록되는 경로입니다.
• registry['internal_certificate'], 기본적으로 자동으로 생성됨. GitLab이 토큰에 서명하는 데 사용하는 인증서의 내용입니다.
• registry['rootcertbundle'], 기본적으로 프로그래밍 방식으로 설정됨. 인증서에 대한 경로입니다.

이곳은 internal_certificate의 내용이 디스크에 기록되는 경로입니다.

• registry['health_storagedriver_enabled'], 기본적으로 프로그래밍 방식으로 설정됨. 구성된 저장 드라이버에 대한 헬스 체크가 활성화되어 있는지 여부를 구성합니다.
• gitlab_rails['registry_issuer'], 기본값. 이 설정은 레지스트리와 GitLab 간에 동일하게 설정되어야 합니다.

GitLab 구성

아래에서 GitLab이 레지스트리와 별도로 실행되도록 설정해야 하는 구성 옵션을 /etc/gitlab/gitlab.rb에서 찾을 수 있습니다:

• gitlab_rails['registry_enabled']는 true로 설정해야 합니다. 이 설정은 GitLab에 레지스트리 API 요청을 허용해야 함을 알립니다.

• gitlab_rails['registry_api_url']는 기본적으로 프로그램으로 설정됨. 이는 사용자가 상호작용할 필요가 없는 내부적으로 사용되는 레지스트리 URL입니다, registry['registry_http_addr']와 함께 스킴을 사용합니다.

• gitlab_rails['registry_host'], 예를 들어, registry.gitlab.example. 스킴이 없는 레지스트리 엔드포인트로, 최종 사용자에게 표시되는 주소입니다.

• gitlab_rails['registry_port']. 최종 사용자에게 표시되는 레지스트리 엔드포인트 포트입니다.

• gitlab_rails['registry_issuer']는 레지스트리 구성의 발급자와 일치해야 합니다.

• gitlab_rails['registry_key_path'], 레지스트리 측에서 인증서와 일치하는 키의 경로입니다.

• gitlab_rails['internal_key'], GitLab이 토큰에 서명하는 데 사용하는 키의 내용입니다.

GitLab 컨테이너 레지스트리 아키텍처

GitLab 레지스트리는 사용자가 자신의 Docker 이미지를 저장하는 데 사용하는 것입니다.

따라서 레지스트리는 클라이언트와의 상호작용이 필요하며, 이는 웹 서버(또는 로드 밸런서, 줄여서 LB)에서 직접 노출됩니다.

위 다이어그램에 설명된 흐름:

1. 사용자가 자신의 클라이언트에서 docker login registry.gitlab.example를 실행합니다. 이는 포트 443에서 웹 서버(또는 LB)에 도달합니다.

2. 웹 서버는 레지스트리 백엔드 풀에 연결합니다(기본적으로 포트 5000 사용). 사용자가 유효한 토큰을 제공하지 않았기 때문에, 레지스트리는 401 HTTP 코드를 반환하고, 토큰을 받을 수 있는 URL(token_realm 레지스트리 구성에서)로 안내합니다. 이는 GitLab API를 가리킵니다.

3. Docker 클라이언트는 그 후 GitLab API에 연결하여 토큰을 얻습니다.

4. API는 레지스트리 키로 토큰에 서명하고 이를 Docker 클라이언트에 전달합니다.

5. Docker 클라이언트는 이제 API로부터 받은 토큰으로 다시 로그인합니다. 이제 Docker 이미지를 푸시하고 풀할 수 있습니다.

참고: https://distribution.github.io/distribution/spec/auth/token/

GitLab과 레지스트리 간의 통신

레지스트리는 내부적으로 사용자를 인증할 방법이 없으므로 GitLab에 자격 증명 검증을 의존합니다. 레지스트리와 GitLab 간의 연결은 TLS로 암호화됩니다. 키는 GitLab이 토큰에 서명하는 데 사용되며, 인증서는 레지스트리가 서명을 검증하는 데 사용됩니다. 기본적으로 모든 설치에 대해 자체 서명된 인증서 키 쌍이 생성됩니다. 필요에 따라 이를 재정의할 수 있습니다.

GitLab은 레지스트리 개인 키를 사용하여 레지스트리와 상호 작용합니다. 레지스트리 요청이 나갈 때, 짧은 생명(10분) 네임스페이스 제한 토큰이 생성되어 개인 키로 서명됩니다. 그런 다음 레지스트리는 서명이 구성에서 지정된 레지스트리 인증서와 일치하는지 확인하고 작업을 허용합니다. GitLab 배경 작업 처리(Sidekiq를 통해) 또한 레지스트리와 상호작용합니다. 이 작업은 이미지 삭제를 처리하기 위해 레지스트리와 직접 통신합니다.

타사 레지스트리에서 마이그레이션

GitLab에서 외부 컨테이너 레지스트리 사용은 GitLab 15.8에서 사용 중단됨이며, 지원 종료는 GitLab 16.0에서 발생했습니다. 자세한 내용은 사용 중단 통지를 참조하세요.

GitLab 16.0에서는 통합이 비활성화되지 않지만, 문제를 디버깅하고 수정하는 지원은 더 이상 제공되지 않습니다. 또한 통합은 더 이상 개발되지 않으며 새로운 기능으로 향상되지 않습니다. 타사 레지스트리 기능은 새로운 GitLab 컨테이너 레지스트리 버전이 자체 관리형으로 제공된 이후에 완전히 제거될 수 있습니다(에픽 5521 참조). GitLab 컨테이너 레지스트리만 지원될 계획입니다.

이 섹션은 타사 레지스트리에서 GitLab 컨테이너 레지스트리로 마이그레이션하는 관리자를 위한 가이드를 제공합니다. 이곳에 나열되지 않은 타사 컨테이너 레지스트리를 사용하는 경우, 피드백 문제에 사용 사례를 설명할 수 있습니다.

아래 제공된 모든 지침을 먼저 테스트 환경에서 시도해야 합니다. 프로덕션 환경에 복제하기 전에 모든 것이 예상대로 작동하는지 확인하세요.

도커 배포 레지스트리

도커 배포 레지스트리는 CNCF에 기증되었으며 현재 배포 레지스트리로 알려져 있습니다.

이 레지스트리는 GitLab 컨테이너 레지스트리가 기반으로 하는 오픈 소스 구현입니다.

GitLab 컨테이너 레지스트리는 배포 레지스트리가 제공하는 기본 기능과 호환되며, 모든 지원되는 스토리지 백엔드를 포함합니다.

GitLab 컨테이너 레지스트리로 마이그레이션하려면 이 페이지의 지침을 따르세요, 그리고 배포 레지스트리와 동일한 스토리지 백엔드를 사용하세요.

GitLab 컨테이너 레지스트리는 배포 레지스트리에서 사용 중인 것과 동일한 구성을 수용해야 합니다.