- 컨테이너 레지스트리 활성화
- 컨테이너 레지스트리 도메인 구성
- 전체 사이트에서 컨테이너 레지스트리 비활성화
- 신규 프로젝트 전체에서 컨테이너 레지스트리 비활성화
- 컨테이너 레지스트리의 리포지터리 구성
- 레지스트리의 내부 포트 변경
- 프로젝트별로 컨테이너 레지스트리 비활성화
- GitLab을 인증 엔드포인트로 사용하여 외부 컨테이너 레지스트리 사용
- 컨테이너 레지스트리 알림 구성
- 정책 정리 지금 실행하기
- 컨테이너 레지스트리 메타데이터 데이터베이스
- 컨테이너 레지스트리 가비지 수집
- 별도 노드에서 GitLab 및 레지스트리 구성하기 (Linux 패키지 설치)
- GitLab 컨테이너 레지스트리 아키텍처
- 서드파티 레지스트리에서 마이그레이션
- 문제 해결
GitLab 컨테이너 레지스트리 관리
GitLab 컨테이너 레지스트리를 사용하면 각 프로젝트마다 Docker 이미지를 저장할 수 있는 공간을 갖게 됩니다.
Distribution Registry에 대한 자세한 내용은 다음을 참조하세요:
이 문서는 관리자 가이드입니다. GitLab 컨테이너 레지스트리를 사용하는 방법에 대해서는 사용자 설명서를 참조하십시오.
컨테이너 레지스트리 활성화
컨테이너 레지스트리를 활성화하는 방법은 사용하는 설치 유형에 따라 다릅니다.
Linux 패키지 설치
Linux 패키지를 사용하여 GitLab을 설치한 경우, 컨테이너 레지스트리는 기본적으로 사용 가능하거나 사용 중이지 않을 수 있습니다.
내장된 Let’s Encrypt 통합을 사용하는 경우, 컨테이너 레지스트리는 자동으로 활성화되어 GitLab 도메인의 5050 포트에서 사용할 수 있습니다.
그렇지 않은 경우, 컨테이너 레지스트리는 활성화되지 않습니다. 활성화하려면:
- 기존 GitLab 도메인에 대해 구성, 또는
- 다른 도메인에 대해 구성할 수 있습니다.
컨테이너 레지스트리는 기본적으로 HTTPS에서 작동합니다. HTTP를 사용할 수도 있지만 권장되지 않으며, 이에 대한 설명은 이 문서의 범위를 벗어나므로 포함되지 않습니다.
자체 컴파일된 설치
GitLab 설치를 자체 컴파일한 경우:
- 설치 중 GitLab 버전에 해당하는 이미지를 사용하여 레지스트리를 배포해야 합니다
(예:
registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab
) - 설치가 완료된 후, 해당 레지스트리를 활성화하려면
gitlab.yml
에서 레지스트리 설정을 구성해야 합니다. - NGINX 구성 파일의 샘플은 다음과 같습니다.
lib/support/nginx/registry-ssl
에서 찾아 해당 호스트, 포트 및 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
여기서:
매개변수 | 설명 |
---|---|
enabled
|
true 또는 false . GitLab에서 레지스트리를 활성화합니다. 기본적으로 false 입니다.
|
host
| 레지스트리가 실행되고 사용자가 사용할 수 있는 호스트 URL입니다. |
port
| 외부 레지스트리 도메인이 수신하는 포트입니다. |
api_url
| 레지스트리가 노출된 내부 API URL입니다. 기본값은 http://localhost:5000 입니다. 외부 Docker 레지스트리를 설정하는 경우가 아니라면 이를 변경하지 마십시오.
|
key
| 이는 레지스트리의 rootcertbundle 과 같은 비공개 키의 위치입니다.
|
path
| 이는 레지스트리의 rootdirectory 에서 지정한 것과 동일해야 합니다. 이 경로는 GitLab 사용자, 웹 서버 사용자 및 레지스트리 사용자가 읽을 수 있어야 합니다.
|
issuer
| 이는 레지스트리의 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
auth
가 설정되지 않은 경우 사용자는 인증 없이 Docker 이미지를 가져올 수 있습니다.컨테이너 레지스트리 도메인 구성
레지스트리의 외부 도메인을 다음 중 하나의 방법으로 구성할 수 있습니다:
- 기존 GitLab 도메인 사용. 레지스트리는 포트에서 수신하고 기존 GitLab의 TLS 인증서를 재사용합니다.
- 새로운 TLS 인증서를 사용하여 완전히 별도의 도메인 사용.
컨테이너 레지스트리는 TLS 인증서가 필요하므로 비용이 발생할 수 있습니다.
첫 번째 구성 전에 이를 고려하십시오.
기존 GitLab 도메인 아래 컨테이너 레지스트리 구성
컨테이너 레지스트리가 기존 GitLab 도메인을 사용하도록 구성된 경우, 레지스트리를 포트에 노출할 수 있습니다. 이렇게 하면 기존 GitLab TLS 인증서를 재사용할 수 있습니다.
GitLab 도메인이 https://gitlab.example.com
이고 외부 세계로 나가는 포트가 5050
이라면, 이렇게 컨테이너 레지스트리를 구성할 수 있습니다:
- Linux 패키지 설치를 사용하는 경우
gitlab.rb
를 편집합니다. - 자체 컴파일된 설치를 사용하는 경우
gitlab.yml
를 편집합니다.
레지스트리가 기본적으로 사용하는 5000 포트와 중복되지 않는 포트를 선택해야 합니다. 그렇지 않으면 충돌이 발생할 수 있습니다.
registry_external_url
행 하단에 나열된 포트를 통해 들어오는 트래픽을 허용하도록 구성되어야 합니다. 이때의 포트는 gitlab_rails['registry_port']
(기본값 5000
) 아래에 나열된 것이 아니라 registry_external_url
행 하단에 나열된 것입니다.-
/etc/gitlab/gitlab.rb
파일에는 레지스트리 URL 및 기존 GitLab에서 사용하는 TLS 인증서 및 키의 경로가 포함되어 있어야 합니다:registry_external_url 'https://gitlab.example.com:5050'
registry_external_url
은 기존 GitLab URL의 HTTPS에서 사용되지만 다른 포트에서 사용됩니다.TLS 인증서가
/etc/gitlab/ssl/gitlab.example.com.crt
에 없고 키가/etc/gitlab/ssl/gitlab.example.com.key
에 없는 경우 아래 줄들을 주석 처리해야 합니다:registry_nginx['ssl_certificate'] = "/path/to/certificate.pem" registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.
-
다음 명령을 사용하여 유효성을 검사합니다.
openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem
인증서 제공 업체가 CA 번들 인증서를 제공하는 경우 이를 TLS 인증서 파일에 추가하십시오.
관리자는 레지스트리가 5678
과 같은 임의의 포트에서 수신하도록 할 수 있습니다.
그러나 레지스트리 및 응용 프로그램 서버는 80
및 443
포트만 수신하는 AWS 응용 프로그램 로드 밸런서 뒤에 있습니다. 관리자는 registry_external_url
에 대한 포트 번호를 제거하여 HTTP 또는 HTTPS로 가정하는 규칙을 적용해야 합니다. 이는 사용자가 컨테이너 레지스트리의 docker login
예제에 의존하는 경우에 중요합니다. 다음은 예시입니다:
registry_external_url 'https://registry-gitlab.example.com'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678
-
/home/git/gitlab/config/gitlab.yml
을 열고registry
항목을 찾아 다음과 같이 구성하세요:registry: enabled: true host: gitlab.example.com port: 5050
- 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.
- NGINX에서도 관련 변경사항을 적용하세요(도메인, 포트, TLS 인증서 경로).
이제 사용자는 다음을 사용하여 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에 의해 자동으로 생성된 인증서도 리눅스 패키지 설치에서 지원됩니다.
컨테이너 레지스트리를 https://registry.gitlab.example.com
에서 접근할 수 있도록 원한다고 가정해 봅시다.
-
TLS 인증서와 키를
/etc/gitlab/ssl/registry.gitlab.example.com.crt
및/etc/gitlab/ssl/registry.gitlab.example.com.key
에 배치하고 올바른 권한이 있는지 확인합니다:chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
-
TLS 인증서가 준비되면
/etc/gitlab/gitlab.rb
를 편집합니다:registry_external_url 'https://registry.gitlab.example.com'
registry_external_url
은 HTTPS로 수신 대기하고 있습니다. -
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성합니다.
와일드카드 인증서가 있는 경우에는 URL에 추가로 인증서의 경로를 지정해야 합니다. 이 경우 /etc/gitlab/gitlab.rb
는 다음과 같이 보일 것입니다:
registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
-
/home/git/gitlab/config/gitlab.yml
을 열고registry
항목을 찾아 다음 설정으로 구성합니다:registry: enabled: true host: registry.gitlab.example.com
- 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.
- NGINX에서도 관련 변경 사항(도메인, 포트, TLS 인증서 경로)을 수행합니다.
사용자들은 이제 GitLab 자격 증명을 사용하여 컨테이너 레지스트리에 로그인할 수 있어야 합니다:
docker login registry.gitlab.example.com
전체 사이트에서 컨테이너 레지스트리 비활성화
이러한 단계를 따라 레지스트리를 비활성화하면 기존의 Docker 이미지는 제거되지 않습니다. Docker 이미지 제거는 레지스트리 응용 프로그램 자체에서 처리됩니다.
-
/etc/gitlab/gitlab.rb
를 열고registry['enable']
를false
로 설정합니다:registry['enable'] = false
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.
-
/home/git/gitlab/config/gitlab.yml
을 열고enabled
를false
로 설정합니다:registry: enabled: false
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.
신규 프로젝트 전체에서 컨테이너 레지스트리 비활성화
컨테이너 레지스트리가 활성화된 경우 모든 신규 프로젝트에서 해당 기능을 사용할 수 있습니다. 이 기능을 비활성화하고 프로젝트 소유자가 직접 컨테이너 레지스트리를 활성화할 수 있도록 하려면 다음 단계를 따르세요.
-
/etc/gitlab/gitlab.rb
를 편집하고 다음 라인을 추가합니다:gitlab_rails['gitlab_default_projects_features_container_registry'] = false
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.
-
/home/git/gitlab/config/gitlab.yml
을 열고default_projects_features
항목을 찾아container_registry
를false
로 설정합니다:## Default project features settings default_projects_features: issues: true merge_requests: true wiki: true snippets: false builds: true container_registry: false
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.
토큰 기간 증가
GitLab에서 컨테이너 레지스트리의 토큰은 매 5분마다 만료됩니다. 토큰 기간을 증가시키려면:
- 왼쪽 사이드 바에서 관리 영역을 선택합니다.
- 설정 > CI/CD를 선택합니다.
- 컨테이너 레지스트리를 확장합니다.
- 인가 토큰 기간(분)에 대한 값을 업데이트합니다.
- 변경 사항 저장을 선택합니다.
컨테이너 레지스트리의 리포지터리 구성
컨테이너 레지스트리는 다양한 리포지터리 백엔드를 사용하도록 구성할 수 있습니다. 기본적으로 GitLab 컨테이너 레지스트리는 파일 시스템 드라이버 구성을 사용합니다.
지원되는 드라이버는 다음과 같습니다:
드라이버 | 설명 |
---|---|
filesystem
| 로컬 파일 시스템의 경로 사용 |
azure
| Microsoft Azure Blob Storage |
gcs
| Google Cloud Storage |
s3
| Amazon Simple Storage Service. 올바른 S3 Permission Scopes로 저장 버킷을 구성해야 합니다. |
대부분의 S3 호환 서비스(예: MinIO)는 컨테이너 레지스트리와 함께 작동해야 하지만, 우리는 AWS S3에 대한 지원을 보장할 뿐입니다. 제3자 S3 구현의 정확성을 단언할 수 없기 때문에 문제를 진단할 수는 있지만, 문제가 AWS S3 버킷에서 재현되기 전에는 레지스트리를 수정할 수 없습니다.
드라이버 | 설명 |
---|---|
swift
| OpenStack Swift Object Storage |
oss
| Aliyun OSS |
파일 시스템 사용
이미지를 파일 시스템에 저장하려면 컨테이너 레지스트리의 저장 경로를 변경할 수 있습니다. 아래 단계를 따르세요.
이 경로는 다음에 액세스할 수 있습니다:
- 컨테이너 레지스트리 데몬을 실행하는 사용자.
- GitLab을 실행하는 사용자.
모든 GitLab, Registry 및 웹 서버 사용자는 이 디렉터리에 액세스해야 합니다.
리눅스 패키지 설치의 기본 이미지 저장 위치는 /var/opt/gitlab/gitlab-rails/shared/registry
입니다. 변경하려면:
-
/etc/gitlab/gitlab.rb
를 편집하세요:gitlab_rails['registry_path'] = "/path/to/registry/storage"
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성합니다.
자체 컴파일 설치의 기본 이미지 저장 위치는 /home/git/gitlab/shared/registry
입니다. 변경하려면:
-
/home/git/gitlab/config/gitlab.yml
을 열고registry
항목을 찾아path
설정을 변경하세요:registry: path: shared/registry
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.
객체 스토리지 사용
객체 스토리지에 이미지를 저장하려면 컨테이너 레지스트리의 저장 드라이버를 변경할 수 있습니다.
GitLab에서 객체 스토리지 사용에 대해 자세히 알아보기.
리눅스 패키지 설치를 위한 s3
및 gcs
저장 드라이버 구성
다음 구성 단계는 s3
및 gcs
저장 드라이버를 위한 것입니다. 다른 저장 드라이버도 지원됩니다.
리눅스 패키지 설치를 위해 s3
저장 드라이버를 구성하려면:
-
/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
은host/bucket_name/object
스타일 경로 대신bucket_name.host/object
를 사용하도록 true로 설정하세요. AWS S3를 위해 false로 설정하세요.
S3 API에서의 503 오류를 피하기 위해 S3 연결의 요청 속도 제한을 설정할 수 있습니다. 이를 위해
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 } }
-
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성합니다.
리눅스 패키지 설치를 위해 gcs
저장 드라이버를 구성하려면:
-
/etc/gitlab/gitlab.rb
를 편집하세요:registry['storage'] = { 'gcs' => { 'bucket' => 'BUCKET_NAME', 'keyfile' => 'PATH/TO/KEYFILE', # 레지스트리 이외의 다른 앱과 버킷을 공유하는 경우, 다음을 주석 처리하세요: # 'rootdirectory' => '/gcs/object/name/prefix' } }
GitLab은 사용 가능한 모든 매개변수를 지원합니다.
-
파일을 저장하고 변경 사항이 적용되도록 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
CLI를 사용합니다. 이전에 CLI를 구성하지 않은 경우sudo aws configure
를 실행하여 자격 증명을 구성해야 합니다. 컨테이너 레지스트리 폴더에 일반 사용자가 액세스할 수 없을 가능성이 높기 때문에sudo
를 사용하도록 주의하세요. 자격 증명 구성을 확인하려면 모든 버킷을 나열하기 위해ls
를 실행하세요.sudo aws --endpoint-url https://your-object-storage-backend.com s3 ls
백엔드로 AWS를 사용하는 경우
--endpoint-url
이 필요하지 않습니다. -
초기 데이터를 S3 버킷에 복사하세요. 예를 들어
aws
CLI의cp
나sync
명령을 사용하세요.docker
폴더를 버킷의 최상위 폴더로 유지하세요.sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket
많은 양의 데이터가 있는 경우 병렬 동기화 작업을 실행하여 성능을 개선할 수 있습니다. - 컨테이너 레지스트리를 읽기 전용으로 설정하고 GitLab을 다시 구성하세요.
-
초기 데이터 로드 이후의 변경 사항을 S3 버킷에 동기화하고 목적지 버킷에만 존재하는 파일을 삭제하세요:
sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket --delete --dryrun
명령이 예상대로 작동하는지 확인한 후
--dryrun
플래그를 제거하고 명령을 실행하세요.--delete
플래그는 목적지에만 존재하는 파일을 삭제합니다. 소스와 대상을 교체하면 레지스트리의 모든 데이터가 삭제됩니다. -
모든 컨테이너 레지스트리 파일이 객체 리포지터리에 업로드되었는지 확인하기 위해 다음 두 명령을 사용하여 반환된 파일 수를 확인하세요:
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
디렉터리 및 하위 디렉터리의 콘텐츠를 제외한 다르지만 일치해야 합니다. - 레지스트리를 S3 버킷을 사용하도록 구성하세요.
- 변경 사항이 적용되도록 레지스트리를 다시
읽기-쓰기
모드로 설정하고 GitLab을 다시 구성하세요.
Azure Object Storage로 이동
- 저장 드라이버의 기본 구성은 GitLab 16.0에서 변경될 예정입니다.
기존 파일 시스템이나 다른 오브젝트 스토리지 공급 업체에서 Azure Object Storage로 이동할 때, 레지스트리를 표준 루트 디렉터리를 사용하도록 구성해야 합니다.
레지스트리 구성의 Azure 저장 드라이버 섹션에 trimlegacyrootprefix: true
를 설정하여 구성하세요.
이 구성을 하지 않으면 Azure 저장 드라이버는 마이그레이션된 이미지에 액세스할 수 없게하는 루트 경로의 첫 번째 섹션으로 /
대신 //
을 사용합니다.
registry['storage'] = {
'azure' => {
'accountname' => 'accountname',
'accountkey' => 'base64encodedaccountkey',
'container' => 'containername',
'rootdirectory' => '/azure/virtual/container',
'trimlegacyrootprefix' => true
}
}
storage:
azure:
accountname: accountname
accountkey: base64encodedaccountkey
container: containername
rootdirectory: /azure/virtual/container
trimlegacyrootprefix: true
기본적으로 Azure Storage Driver는 core.windows.net
영역을 사용합니다. azure
섹션에서 realm
의 다른 값을 설정할 수 있습니다(예: Azure Government Cloud의 경우 core.usgovcloudapi.net
).
스토리지 드라이버의 리다이렉트 비활성화
기본적으로 원격 백엔드로 구성된 레지스트리에 액세스하는 사용자는 스토리지 드라이버의 기본 백엔드로 리디렉션됩니다. 예를 들어, 레지스트리는 요청을 원격 S3 버킷으로 리디렉션하여 GitLab 서버의 부하를 줄일 수 있습니다.
그러나 이 동작은 일반적으로 공용 서버에 액세스할 수 없는 내부 호스트에서 사용되는 레지스트리에는 원하지 않는 동작입니다. 리디렉트를 비활성화하고 프록시 다운로드를 위해 disable
플래그를 다음과 같이 true로 설정하세요. 이는 모든 트래픽이 항상 레지스트리 서비스를 통해 전달되도록 만듭니다. 이는 보안이 향상되었지만(스토리지 백엔드가 공개적으로 접근할 수 없기 때문에 공격 표면이 줄어듦), 성능이 저하됩니다(모든 트래픽이 서비스를 통해 리디렉션됨).
-
/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' }, 'redirect' => { 'disable' => true } }
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.
-
레지스트리 구성 YAML 파일에
redirect
플래그를 추가하세요:storage: s3: accesskey: 'AKIAKIAKI' secretkey: 'secret123' bucket: 'gitlab-registry-bucket-AKIAKIAKI' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' redirect: disable: true cache: blobdescriptor: inmemory delete: enabled: true
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재시작하세요.
암호화된 S3 버킷
S3 버킷에 AWS KMS의 서버 측 암호화를 사용할 수 있습니다. 기본적으로 SSE-S3 또는 SSE-KMS 암호화가 기본적으로 활성화된 S3 버킷에 대해 encrypt
옵션을 활성화해야 합니다. 이는 모든 요청에 암호화 키를 보내야 하기 때문에 고객 마스터 키(CMKs) 및 SSE-C 암호화를 지원하지 않습니다.
SSE-S3의 경우, 레지스트리 설정에서 encrypt
옵션을 활성화해야 합니다. 이를 하는 방법은 GitLab을 어떻게 설치했냐에 따라 다릅니다. 설치 방법과 일치하는 지침에 따라 작업하세요.
-
/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', 'encrypt' => true } }
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.
-
레지스트리 구성 YAML 파일을 편집하세요:
storage: s3: accesskey: 'AKIAKIAKI' secretkey: 'secret123' bucket: 'gitlab-registry-bucket-AKIAKIAKI' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' encrypt: true
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재시작하세요.
스토리지 제한
사용자는 무한한 양의 임의 크기 이미지를 업로드할 수 있는 저장 공간 제한이 없습니다. 이 설정은 향후 릴리스에서 구성 가능해야 합니다.
레지스트리의 내부 포트 변경
레지스트리 서버는 기본적으로 로컬에서 5000
포트에서 대기하며, 레지스트리 서버가 연결을 수락해야 하는 주소입니다. 아래 예제에서는 레지스트리의 포트를 5010
으로 설정합니다.
-
/etc/gitlab/gitlab.rb
파일을 열고registry['registry_http_addr']
를 설정하세요:registry['registry_http_addr'] = "localhost:5010"
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.
-
레지스트리 서버의 구성 파일을 열고
http:addr
값을 편집하세요:http: addr: localhost:5010
-
파일을 저장하고 레지스트리 서버를 다시 시작하세요.
프로젝트별로 컨테이너 레지스트리 비활성화
GitLab 인스턴스에서 레지스트리가 활성화되어 있지만 프로젝트에는 필요하지 않은 경우, 프로젝트 설정에서 비활성화할 수 있습니다.
GitLab을 인증 엔드포인트로 사용하여 외부 컨테이너 레지스트리 사용
외부 컨테이너 레지스트리를 사용하는 경우 컨테이너 레지스트리와 관련된 일부 기능이 사용할 수 없거나 내재된 위험이 있을 수 있습니다.
통합이 작동하려면 외부 레지스트리가 GitLab과의 인증을 위해 JSON Web Token을 사용하도록 구성되어야 합니다. 외부 레지스트리의 런타임 구성에 다음 엔트리가 반드시 있어야 합니다:
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
와 같은), registry.example.com/group/project:tag
만 인식합니다.
Linux 패키지 설치
외부 컨테이너 레지스트리를 사용하여 GitLab을 인증 엔드포인트로 사용할 수 있습니다.
-
/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'] = "https://<external_registry_host>:5000"
은 레지스트리가 설치된 호스트와 일치하도록 변경해야 합니다. 외부 레지스트리가 TLS를 사용하도록 구성된 경우에는https
를 지정해야 합니다.
-
-
GitLab 및 외부 컨테이너 레지스트리 간의 안전한 통신을 위해 인증서-키 쌍이 필요합니다. 공개 인증서(
rootcertbundle
)로 외부 컨테이너 레지스트리를 구성하고 개인 키로 GitLab을 구성해야 합니다. 이를 위해/etc/gitlab/gitlab.rb
에 다음을 추가합니다:# registry['internal_key']에 커스텀 키 파일의 내용을 포함해야 합니다. 키 파일의 줄 바꿈은 `\n` 문자로 표시되어야 합니다. # 예시: registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n" # 리눅스 패키지 설치를 위해 registry['internal_key']의 내용을 작성하는 사용자 정의 파일을 선택적으로 정의합니다. gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
재구성이 실행될 때마다
registry_key_path
에서 지정된 파일에internal_key
에 의해 지정된 내용으로 채워집니다. 파일이 지정되지 않은 경우, 리눅스 패키지 설치는 기본적으로/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key
로 지정하고 채웁니다. -
GitLab 컨테이너 레지스트리 페이지에 표시되는 컨테이너 레지스트리 URL을 변경하려면 다음 구성을 설정하세요:
gitlab_rails['registry_host'] = "registry.gitlab.example.com" gitlab_rails['registry_port'] = "5005"
-
파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성을 수행하세요.
직접 컴파일된 설치
-
/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
이러한 매개변수의 의미에 대한 자세한 내용은 여기에서 읽어보세요.
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.
컨테이너 레지스트리 알림 구성
레지스트리를 구성하여 레지스트리에서 발생하는 이벤트에 대한 웹훅 알림을 보내도록 설정할 수 있습니다.
Docker Registry 알림 설명서에서 컨테이너 레지스트리 알림 구성 옵션에 대해 자세히 알아보세요.
컨테이너 레지스트리에 대해 여러 엔드포인트를 구성할 수 있습니다.
:::Tabs
리눅스 패키지 설치용 알림 엔드포인트를 구성하려면 다음을 수행하세요:
-
/etc/gitlab/gitlab.rb
파일을 편집합니다:registry['notifications'] = [ { 'name' => 'test_endpoint', 'url' => 'https://gitlab.example.com/notify', 'timeout' => '500ms', 'threshold' => 5, # DEPRECATED: use `maxretries` instead. 'maxretries' => 5, 'backoff' => '1s', 'headers' => { "Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"] } } ]
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.
알림 엔드포인트 구성은 Docker 레지스트리를 배포할 때 생성된 레지스트리 구성 YAML 파일에서 수행합니다.
예시:
notifications:
endpoints:
- name: alistener
disabled: false
url: https://my.listener.com/event
headers: <http.Header>
timeout: 500
threshold: 5 # DEPRECATED: use `maxretries` instead.
maxretries: 5
backoff: 1000
::EndTabs
정책 정리 지금 실행하기
- Sidekiq 노드의
gitlab.rb
파일을 올바른 레지스트리 URL을 가리키도록 구성합니다. -
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 = <프로젝트 ID>
# 프로젝트에 대한 Developer, Maintainer 또는 Owner 역할을 갖는 사용자의 숫자 ID
U = <사용자 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
Status: Beta
메타데이터 데이터베이스를 사용하면 온라인 가비지 수집과 같은 다양한 레지스트리 기능이 가능해지며, 다양한 레지스트리 작업의 효율성이 증가합니다. 자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스 페이지를 참조하십시오.
컨테이너 레지스트리 가비지 수집
Amazon S3 Lifecycle과 같은 오브젝트 스토리지 제공 업체의 보존 정책은 객체가 제대로 삭제되지 못하도록 할 수 있습니다.
컨테이너 레지스트리는 상당량의 저장 공간을 사용할 수 있으며, 저장 공간 사용량을 줄이려면 희망할 수 있습니다. 나열된 옵션 중에서 태그 삭제가 가장 효과적인 옵션입니다. 그러나 태그 삭제만으로는 이미지 레이어를 삭제하지 않고 기본 이미지 매니페스트를 태그 해제만 합니다.
더 효과적으로 공간을 확보하려면 컨테이너 레지스트리에는 참조되지 않는 레이어와 (선택적으로) 태그 해제된 매니페스트를 삭제할 수 있는 가비지 수집기가 있습니다.
가비지 수집기를 실행하려면 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
의 매니페스트를 가리킵니다. 레지스트리의 아키텍처로 인해 이 데이터는 :latest
태그로는 더 이상 직접 액세스할 수는 없지만 이미지 my.registry.com/my.group/my.project@sha256:111111
을 가져올 때에는 여전히 액세스할 수 있습니다.
참조되지 않는 레이어 제거
이미지 레이어는 컨테이너 레지스트리 저장 공간의 대부분을 차지합니다. 이미지 매니페스트가 해당 레이어를 참조하지 않을 때 레이어는 참조되지 않는 것으로 간주됩니다. 참조되지 않는 레이어는 컨테이너 레지스트리 가비지 수집 기본 대상입니다.
기본 구성 파일의 위치를 변경하지 않은 경우 다음 명령을 실행하십시오:
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
명령을 우회해야합니다.
레지스트리를 읽기 전용으로 설정하면 이미지를 가져올 수 있지만 이미지를 푸시할 수는 없습니다. 가비지 수집 기간 동안 컨테이너 레지스트리는 계속해서 읽기 전용 상태여야합니다.
기본적으로 레지스트리 저장 경로는 /var/opt/gitlab/gitlab-rails/shared/registry
입니다.
읽기 전용 모드를 활성화하려면:
-
/etc/gitlab/gitlab.rb
에서 읽기 전용 모드를 지정하십시오:registry['storage'] = { 'filesystem' => { 'rootdirectory' => "<your_registry_storage_path>" }, 'maintenance' => { 'readonly' => { 'enabled' => true } } }
-
저장하고 GitLab을 다시 구성하십시오:
sudo gitlab-ctl reconfigure
이 명령은 컨테이너 레지스트리를 읽기 전용 모드로 설정합니다.
-
이제 가비지 수집 명령 중 하나를 실행하십시오:
# 참조 없는 레이어 제거 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
이 명령은 가비지 수집을 시작합니다. 완료까지 걸리는 시간은 레지스트리 데이터 크기에 비례합니다.
-
완료되면
/etc/gitlab/gitlab.rb
에서 다시 읽기/쓰기 모드로 변경하십시오:registry['storage'] = { 'filesystem' => { 'rootdirectory' => "<your_registry_storage_path>" }, 'maintenance' => { 'readonly' => { 'enabled' => false } } }
-
저장하고 GitLab을 다시 구성하십시오:
sudo gitlab-ctl reconfigure
일정에 따른 가비지 수집 실행
이상적으로는 레지스트리 사용이 없는 시간에 매주 정기적으로 레지스트리의 가비지 수집을 실행하고 싶을 것입니다. 가장 간단한 방법은 매주 한 번 주간에 주기적으로 실행되는 크론탭 작업을 추가하는 것입니다.
/etc/cron.d/registry-garbage-collect
파일을 만들어 주일요일 04:05am에 매주 실행하도록 설정하십시오:
SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
# 매주 일요일 04:05am에 실행
5 4 * * 0 root gitlab-ctl registry-garbage-collect
태그 해제된 매니페스트 및 참조되지 않는 레이어를 제거하기 위해 -m
플래그를 추가할 수 있습니다.
가비지 수집 중지
가비지 수집을 중지할 예정인 경우 다운타임 없이 가비지 수집 실행에서 설명한 대로 가비지 수집을 매뉴얼으로 실행해야합니다. 그런 다음 gitlab-ctl
을 중지할 수 있습니다.
그렇지 않으면 gitlab-ctl
을 중지하면 레지스트리 서비스가 중단될 수 있습니다. 이 경우 가비지 수집 프로세스를 시스템에서 찾아 gitlab-ctl
명령으로 레지스트리 서비스를 다시 실행할 수 있어야합니다.
또한 프로세스의 마크 단계 중에 진행 상황이나 결과를 저장할 수는 없습니다. 실제로 삭제가 시작되기 전에는 영구적인 작업이 수행되지 않습니다.
지속적인 영구 다운타임 가비지 수집
메타데이터 데이터베이스로 이전하면 일정을 예약하거나 읽기 전용 모드가 필요하지 않고 백그라운드에서 가비지 수집을 실행할 수 있습니다.
별도 노드에서 GitLab 및 레지스트리 구성하기 (Linux 패키지 설치)
기본적으로 패키지는 두 서비스가 동일한 노드에서 실행되고 있다고 가정합니다. GitLab 및 레지스트리를 별도의 노드에서 실행하려면 레지스트리 및 GitLab에 대한 별도의 설정이 필요합니다.
레지스트리 구성
별도로 실행하기 위해 /etc/gitlab/gitlab.rb
에 설정해야 하는 레지스트리의 구성 옵션은 다음과 같습니다:
-
registry['registry_http_addr']
, 기본값 프로그래밍적으로 설정. 웹 서버(또는 로드 밸런서)에서 접근 가능해야 합니다. -
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 구성
별도로 실행하기 위해 /etc/gitlab/gitlab.rb
에 설정해야 하는 GitLab의 구성 옵션은 다음과 같습니다:
-
gitlab_rails['registry_enabled']
,true
로 설정해야 합니다. 이 설정은 GitLab에게 레지스트리 API 요청을 허용해야 함을 나타냅니다. -
gitlab_rails['registry_api_url']
, 기본값 프로그래밍적으로 설정. 사용자가 상호 작용할 필요가 없는 내부적으로 사용되는 레지스트리 URL입니다.registry['registry_http_addr']
와 scheme이 있습니다. -
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)에 직접 노출됩니다.
위 다이어그램에 설명된 흐름:
- 사용자가 클라이언트에서
docker login registry.gitlab.example
를 실행합니다. 이는 포트 443에서 웹 서버(또는 LB)에 도달합니다. - 웹 서버는 레지스트리 백엔드 풀(기본적으로 포트 5000을 사용)에 연결합니다. 사용자가 유효한 토큰 제공하지 않았기 때문에, 레지스트리는 401 HTTP 코드와 사용자가 토큰을 받을 URL인
token_realm
(레지스트리 구성에서)을 반환합니다. 이 URL은 GitLab API를 가리킵니다. - Docker 클라이언트는 GitLab API에 연결하여 토큰을 얻습니다.
- API는 토큰을 레지스트리 키로 서명하고 Docker 클라이언트에 전달합니다.
- Docker 클라이언트는 이제 API로부터 받은 토큰으로 다시 로그인합니다. 이제 Docker 이미지를 푸시하고 끌어올 수 있습니다.
참조: https://distribution.github.io/distribution/spec/auth/token/
GitLab과 레지스트리 간 통신
레지스트리에는 내부적으로 사용자를 인증하는 방법이 없으므로 GitLab이 자격 증명을 검증하도록 의존합니다. 레지스트리와 GitLab 간의 연결은 TLS로 암호화됩니다. 키는 GitLab에서 토큰에 서명하는 데 사용되며, 인증서는 레지스트리가 서명을 검증하는 데 사용됩니다. 기본적으로 자체 서명된 인증서 키 쌍이 모든 설치에 대해 생성됩니다. 필요에 따라이를 재정의할 수 있습니다.
GitLab은 레지스트리 개인 키를 사용하여 레지스트리와 상호 작용합니다. 레지스트리 요청을 보낼 때, 새로운 단기간(10분)의 namespace 제한 토큰이 생성되고 개인 키로 서명됩니다. 레지스트리는 그 서명이 구성된 레지스트리 인증서와 일치하는지 확인하고 작업을 허용합니다. GitLab 백그라운드 작업 처리(Sidekiq을 통해)도 레지스트리와 상호 작용합니다. 이러한 작업은 이미지 삭제를 처리하기 위해 레지스트리에 직접 대화합니다.
서드파티 레지스트리에서 마이그레이션
GitLab에서 외부 컨테이너 레지스트리 사용은 GitLab 15.8에서 사용 중단되었으며 지원 종료는 GitLab 16.0에서 발생했습니다. 자세한 내용은 사용 중단 공지에서 확인하세요.
GitLab 16.0에서 통합은 비활성화되지는 않았지만 디버깅 및 문제 해결 지원은 더 이상 제공되지 않습니다. 또한, 해당 통합은 더 이상 개발되거나 새로운 기능으로 강화되지 않습니다. 새로운 GitLab 컨테이너 레지스트리 버전이 Self-Managed형 형식으로 사용 가능한 후에는 외부 레지스트리 기능이 완전히 제거될 수 있습니다(사용자 지정 가능한 에픽 5521 참조).
본 섹션에서는 서드파티 레지스트리에서 GitLab 컨테이너 레지스트리로 마이그레이션하는 관리자를 위한 지침을 제공합니다. 사용 중인 서드파티 컨테이너 레지스트리가 여기에 나열되어 있지 않으면, 사용 사례를 피드백 이슈에 설명할 수 있습니다.
아래 제공된 모든 지침에 대해서는 먼저 테스트 환경에서 시도해 보아야 합니다. 모든 것이 예상대로 계속 작동하는지 확인한 후에 본격적으로 프로덕션 환경에 복제하기 전에 테스트하세요.
Docker Distribution Registry
Docker Distribution Registry는 CNCF에 기증되어 이제 Distribution Registry로 알려지고 있습니다. 이 레지스트리는 GitLab 컨테이너 레지스트리가 기반으로 하는 오픈 소스 구현체입니다. GitLab 컨테이너 레지스트리는 Distribution Registry가 제공하는 기본 기능과 모든 지원되는 리포지터리 백엔드와 호환됩니다. Distribution Registry와 동일한 리포지터리 백엔드를 사용하여 GitLab 컨테이너 레지스트리로 마이그레이션하려면 이 페이지의 지침을 따르면 됩니다. GitLab 컨테이너 레지스트리는 Distribution Registry에 사용하는 구성과 동일하게 허용해야 합니다.
문제 해결
다음 섹션에 들어가기 전에 기본적인 문제 해결 사항을 확인하세요:
-
Docker 클라이언트와 GitLab 서버의 시스템 클록이 동기화되었는지 확인하세요 (예: NTP를 통해).
-
S3를 백업으로 사용하는 경우, IAM 권한과 S3 자격 증명(지역 포함)이 올바른지 다시 확인하세요. 자세한 내용은 샘플 IAM 정책을 참조하세요.
-
레지스트리 로그(예:
/var/log/gitlab/registry/current
) 및 GitLab 프로덕션 로그(예:/var/log/gitlab/gitlab-rails/production.log
)에서 오류를 확인하세요. 거기서 귀하의 단서를 찾을 수 있을 것입니다.
컨테이너 레지스트리에서 자체 서명 인증서 사용하기
컨테이너 레지스트리에 자체 서명 인증서를 사용하는 경우, 다음과 같은 CI 작업 중 문제가 발생할 수 있습니다:
Error response from daemon: Get registry.example.com/v1/users/: x509: certificate signed by unknown authority
명령을 실행 중인 Docker 데몬은 인증 된 CA에 의해 서명된 인증서를 기대하므로 위와 같은 오류가 발생합니다.
GitLab은 컨테이너 레지스트리와 함께 자체 서명 인증서 사용을 기본적으로 지원하지는 않지만 Docker 데몬에 자체 서명 인증서를 신뢰하도록 지시함으로써 작동시킬 수 있습니다 그리고 GitLab Runner config.toml
파일에서 privileged = false
를 설정합니다. privileged = true
로 설정하는 것이 Docker 데몬에 우선합니다:
[runners.docker]
image = "ruby:2.6"
privileged = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
이에 대한 추가 정보: issue 18239.
‘신뢰되지 않은 키로 서명된 토큰’으로 인해 Docker 로그인 시도 실패
레지스트리는 GitLab을 통해 자격 증명을 확인합니다. 레지스트리가 유효한 로그인 시도를 인증하지 못하면 다음과 같은 오류 메시지가 표시됩니다:
# docker login gitlab.company.com:4567
Username: user
Password:
Error response from daemon: login attempt to https://gitlab.company.com:4567/v2/ failed with status: 401 Unauthorized
특히, /var/log/gitlab/registry/current
로그 파일에 다음과 같이 나타납니다:
level=info msg="token signed by untrusted key with ID: "TOKE:NL6Q:7PW6:EXAM:PLET:OKEN:BG27:RCIB:D2S3:EXAM:PLET:OKEN""
level=warning msg="error authorizing context: invalid token" go.version=go1.12.7 http.request.host="gitlab.company.com:4567" http.request.id=74613829-2655-4f96-8991-1c9fe33869b8 http.request.method=GET http.request.remoteaddr=10.72.11.20 http.request.uri="/v2/" http.request.useragent="docker/19.03.2 go/go1.12.8 git-commit/6a30dfc kernel/3.10.0-693.2.2.el7.x86_64 os/linux arch/amd64 UpstreamClient(Docker-Client/19.03.2 \(linux\))"
GitLab은 레지스트리를 위해 인증 토큰을 암호화하기 위해 인증서 키 페어의 양쪽 내용을 사용합니다. 이 메시지는 해당 내용이 일치하지 않음을 의미합니다.
사용 중인 파일을 확인하세요:
-
grep -A6 'auth:' /var/opt/gitlab/registry/config.yml
## 컨테이너 레지스트리 인증서 auth: token: realm: https://gitlab.my.net/jwt/auth service: container_registry issuer: omnibus-gitlab-issuer --> rootcertbundle: /var/opt/gitlab/registry/gitlab-registry.crt autoredirect: false
-
/var/opt/gitlab/gitlab-rails/etc/gitlab.yml
에서Container Registry
확인:## 컨테이너 레지스트리 키 registry: enabled: true host: gitlab.company.com port: 4567 api_url: http://127.0.0.1:5000 # 내부 레지스트리 주소, GitLab이 API와 직접 통신하는 데 사용됨 path: /var/opt/gitlab/gitlab-rails/shared/registry --> key: /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key issuer: omnibus-gitlab-issuer notification_secret:
이 명령어의 출력이 일치한다면, 인증서 키 페어가 일치함을 증명합니다:
/opt/gitlab/embedded/bin/openssl x509 -noout -modulus -in /var/opt/gitlab/registry/gitlab-registry.crt | /opt/gitlab/embedded/bin/openssl sha256
/opt/gitlab/embedded/bin/openssl rsa -noout -modulus -in /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key | /opt/gitlab/embedded/bin/openssl sha256
인증서의 두 부분이 일치하지 않으면, 파일을 제거하고 gitlab-ctl reconfigure
를 실행하여 쌍을 재생성하세요. 존재하는 값으로 /etc/gitlab/gitlab-secrets.json
에서 registry
섹션을 삭제한 후 gitlab-ctl reconfigure
를 실행하여 쌍을 재생성합니다. 새로운 쌍을 생성하려면 자체 서명 된 쌍을 자동으로 생성된 쌍으로 덮어쓴 경우 /etc/gitlab/gitlab-secrets.json
에서 registry
섹션을 삭제하고 gitlab-ctl reconfigure
를 실행하세요.
GitLab 레지스트리와 AWS S3를 사용할 때 큰 이미지를 푸시하는 중 오류가 발생할 경우
GitLab 레지스트리에서 AWS S3를 사용할 때, 큰 이미지를 푸시하는 중 오류가 발생할 수 있습니다. 레지스트리 로그에서 다음과 같은 오류를 확인하세요:
level=error msg="response completed with error" err.code=unknown err.detail="unexpected EOF" err.message="unknown error"
오류를 해결하려면 레지스트리 구성에서 chunksize
값을 지정하세요. 25000000
(25 MB)와 50000000
(50 MB) 사이의 값으로 시작하세요.
-
/etc/gitlab/gitlab.rb
을 편집하세요:registry['storage'] = { 's3' => { 'accesskey' => 'AKIAKIAKI', 'secretkey' => 'secret123', 'bucket' => 'gitlab-registry-bucket-AKIAKIAKI', 'chunksize' => 25000000 } }
-
변경 사항이 적용되려면 파일을 저장하고 GitLab 다시 구성을 실행하세요.
-
config/gitlab.yml
을 편집하세요:storage: s3: accesskey: 'AKIAKIAKI' secretkey: 'secret123' bucket: 'gitlab-registry-bucket-AKIAKIAKI' chunksize: 25000000
-
변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 시작하십시오.
이전 버전의 Docker 클라이언트 지원
GitLab과 함께 제공되는 Docker 컨테이너 레지스트리는 기본적으로 schema1 manifest를 비활성화합니다. 여전히 이전 버전의 Docker 클라이언트(1.9 이하)를 사용 중이라면 이미지를 푸시하는 중에 오류가 발생할 수 있습니다. 자세한 내용은 이슈 4145를 확인하세요.
호환성을 위해 구성 옵션을 추가할 수 있습니다.
-
/etc/gitlab/gitlab.rb
파일을 편집합니다:registry['compatibility_schema1_enabled'] = true
-
변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 구성하십시오.
-
레지스트리를 배포할 때 생성한 YAML 구성 파일을 편집합니다. 다음 스니펫을 추가합니다:
compatibility: schema1: enabled: true
-
변경 사항이 적용되려면 레지스트리를 다시 시작하십시오.
Docker 연결 오류
그룹, 프로젝트 또는 브랜치 이름에 특수 문자가 있는 경우 Docker 연결 오류가 발생할 수 있습니다. 특수 문자로는 다음이 있습니다:
- 선행 언더스코어(_)
- 후행 하이픈/대시(-)
- 두 개의 하이픈/대시
이를 해결하기 위해 그룹 경로를 변경, 프로젝트 경로를 변경하거나 브랜치 이름을 변경할 수 있습니다. 다른 옵션은 이를 인스턴스 수준에서 방지하기 위해 푸시 규칙을 만드는 것입니다.
이미지 푸시 오류
이미지를 푸시하려고 시도할 때 오류가 발생하거나 “다시 시도 중” 루프에 빠진 경우 docker login
은 정상적으로 작동하는 경우 NGINX가 레지스트리로 전달하는 헤더에 문제가 있을 수 있습니다. 기본 권장 NGINX 구성은 이를 처리해야하지만 SSL을 타사 역방향 프록시로 언로드한 사용자 지정 설정에서 발생할 수 있습니다.
이 문제는 Docker 프로젝트 이슈에서 논의되었으며 레지스트리에서 상대적인 URL을 활성화하는 간단한 해결책일 수 있습니다.
-
/etc/gitlab/gitlab.rb
파일을 편집합니다:registry['env'] = { "REGISTRY_HTTP_RELATIVEURLS" => true }
-
변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 구성하십시오.
-
레지스트리를 배포할 때 생성한 YAML 구성 파일을 편집합니다. 다음 스니펫을 추가합니다:
http: relativeurls: true
-
변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 시작하십시오.
레지스트리 디버그 서버 활성화
레지스트리 디버그 서버를 사용하여 문제를 진단할 수 있습니다. 디버그 엔드포인트는 메트릭, 상태 및 프로파일링을 모니터링할 수 있습니다.
레지스트리 디버그 주소를 gitlab.rb
구성에 설정하여 선택적으로 디버그 서버를 활성화할 수 있습니다.
registry['debug_addr'] = "localhost:5001"
설정을 추가한 후 GitLab을 다시 구성하여 변경 사항을 적용하십시오.
curl을 사용하여 디버그 서버에서 디버그 출력을 요청할 수 있습니다.
curl "localhost:5001/debug/health"
curl "localhost:5001/debug/vars"
이름 없는 태그
AWS DataSync를 사용하여 레지스트리 데이터를 S3 버킷으로 또는 버킷 간에 복사하는 경우 각 컨테이너 리포지터리의 루트 경로에 빈 메타데이터 개체가 생성됩니다. 이로 인해 레지스트리는 GitLab UI 및 API에 이름없는 태그로 표시됩니다. 자세한 내용은 이 이슈를 참조하세요.
이를 해결하기 위해 다음 중 하나를 수행할 수 있습니다:
-
영향을 받는 각 리포지터리의 루트에서 빈 객체를 제거하려면 AWS CLI의
rm
명령을 사용하십시오. 최후의/
에 특히 주의하고--recursive
옵션을 사용하지 않도록 주의하십시오:aws s3 rm s3://<bucket>/docker/registry/v2/repositories/<path to repository>/
-
레지스트리 데이터를 새 버킷으로 복사하고 레지스트리가 해당 버킷을 사용하도록 구성하려면 AWS CLI의
sync
명령을 사용하십시오. 이로 인해 빈 객체가 남아 있게 됩니다.
고급 문제 해결
S3 설정에 문제가 있는 경우를 설명하는 구체적인 예제를 사용합니다.
정리 정책 조사
정리 정책이 태그를 삭제하는 이유 또는 삭제하지 않은 이유가 확실하지 않은 경우 Rails 콘솔에서 아래 스크립트를 실행하여 정책의 문제를 진단할 수 있습니다.
repo = ContainerRepository.find(<project_id>)
policy = repo.project.container_expiration_policy
tags = repo.tags
tags.map(&:name)
tags.reject!(&:latest?)
tags.map(&:name)
regex_delete = ::Gitlab::UntrustedRegexp.new("\\A#{policy.name_regex}\\z")
regex_retain = ::Gitlab::UntrustedRegexp.new("\\A#{policy.name_regex_keep}\\z")
tags.select! { |tag| regex_delete.match?(tag.name) && !regex_retain.match?(tag.name) }
tags.map(&:name)
now = DateTime.current
tags.sort_by! { |tag| tag.created_at || now }.reverse! # Lengthy operation
tags = tags.drop(policy.keep_n)
tags.map(&:name)
older_than_timestamp = ChronicDuration.parse(policy.older_than).seconds.ago
tags.select! { |tag| tag.created_at && tag.created_at < older_than_timestamp }
tags.map(&:name)
- 스크립트는 삭제할 태그 디렉터리(
tags
)을 작성합니다. -
tags.map(&:name)
은 제거할 태그 디렉터리을 출력합니다. 이 과정은 시간이 오래 걸립니다. - 각 필터링 후에
tags
디렉터리을 확인하여 의도한 태그가 포함되어 있는지 확인해야 합니다.
푸시 중 예상치 못한 403 오류
사용자가 S3를 백엔드로 한 레지스트리를 활성화하려고 시도했을 때 docker login
단계는 정상적으로 진행되었습니다. 그러나 이미지를 푸시하려고 하면 다음과 같은 출력이 나타납니다:
The push refers to a repository [s3-testing.myregistry.com:5050/root/docker-test/docker-image]
dc5e59c14160: Pushing [==================================================>] 14.85 kB
03c20c1a019a: Pushing [==================================================>] 2.048 kB
a08f14ef632e: Pushing [==================================================>] 2.048 kB
228950524c88: Pushing 2.048 kB
6a8ecde4cc03: Pushing [==> ] 9.901 MB/205.7 MB
5f70bf18a086: Pushing 1.024 kB
737f40e80b7f: Waiting
82b57dbc5385: Waiting
19429b698a22: Waiting
9436069b92a3: Waiting
error parsing HTTP 403 response body: unexpected end of JSON input: ""
이 오류는 모호하며 403이 GitLab Rails 애플리케이션, Docker 레지스트리 또는 다른 곳에서 발생하는지 명확하지 않습니다. 여기서는 로그인이 성공했기 때문에 클라이언트와 레지스트리 간의 통신을 살펴봐야 합니다.
Docker 클라이언트와 레지스트리 간의 REST API에 대한 설명은 Docker 문서에 나와 있습니다. 보통은 Wireshark나 tcpdump를 사용하여 트래픽을 캡처하고 문제가 발생한 곳을 확인합니다. 그러나 Docker 클라이언트와 서버 간의 모든 통신이 HTTPS로 이루어지므로 트래픽을 빠르게 복호화하는 것은 약간 어려울 수 있습니다. 그럼에도 불구하고 인증 키를 알고 있다면 트래픽을 빠르게 복호화할 수 있습니다. 대안으로는 Mitmproxy(중간자 프록시)를 사용할 수 있습니다.
mitmproxy
mitmproxy를 사용하면 클라이언트와 서버 사이에 프록시를 배치하여 모든 트래픽을 검사할 수 있습니다. 하나의 주된 문제는 작동하려면 시스템이 mitmproxy SSL 인증서를 신뢰해야 한다는 것입니다.
다음 설치 지침은 Ubuntu에서 실행되는 것으로 가정합니다:
- mitmproxy 설치.
-
mitmproxy --port 9000
를 실행하여 해당 인증서를 생성합니다. 끝내려면 CTRL-C를 누릅니다. -
~/.mitmproxy
의 인증서를 시스템에 설치합니다:sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt sudo update-ca-certificates
성공적으로 설치되면 출력에 인증서가 추가되었다는 내용이 표시됩니다:
/etc/ssl/certs에서 인증서를 업데이트 중... 1개가 추가되었고, 0개가 제거되었습니다; 완료.
/etc/ca-certificates/update.d 디렉터리에서 후크 실행 중...완료.
설정한 인증서가 제대로 설치되었는지 확인하려면 다음을 실행하세요:
mitmproxy --port 9000
이 명령은 포트 9000
에서 mitmproxy를 실행합니다. 다른 창에서 다음을 실행하세요:
curl --proxy "http://localhost:9000" "https://httpbin.org/status/200"
모든 것이 올바르게 설정된 경우, mitmproxy 창에 정보가 표시되고 curl 명령에 의해 오류가 생성되지 않습니다.
프록시로 Docker 데몬 실행
Docker가 프록시를 통해 연결하려면 Docker 데몬을 적절한 환경 변수로 시작해야 합니다. 가장 쉬운 방법은 Docker를 종료하고(예: sudo initctl stop docker
) 매뉴얼으로 Docker를 실행하는 것입니다. root로 다음을 실행하세요:
export HTTP_PROXY="http://localhost:9000"
export HTTPS_PROXY="http://localhost:9000"
docker daemon --debug
이 명령은 Docker 데몬을 시작하고 모든 연결을 mitmproxy를 통해 프록시합니다.
Docker 클라이언트 실행
이제 mitmproxy와 Docker가 실행 중이므로 로그인을 시도하고 컨테이너 이미지를 푸시할 수 있습니다. 이를 수행하려면 root로 실행해야 할 수도 있습니다. 예를 들어:
docker login s3-testing.myregistry.com:5050
docker push s3-testing.myregistry.com:5050/root/docker-test/docker-image
위 예에서 mitmproxy 창에 다음과 같은 추적을 볼 수 있습니다:
위 이미지는 다음을 보여줍니다:
- 초기 PUT 요청이 201 상태 코드와 함께 정상적으로 처리되었습니다.
- 201이 클라이언트를 S3 버킷으로 리디렉션했습니다.
- AWS 버킷에 대한 HEAD 요청이 403 Unauthorized를 보고했습니다.
이것은 무엇을 의미합니까? 이는 강력히 S3 사용자가 HEAD 요청을 수행할 권한이 없다는 것을 시사합니다. 해결책: IAM 권한을 다시 확인합니다. 적절한 권한이 설정되면 오류가 사라집니다.
gitlab-registry.key
의 누락으로 인한 컨테이너 리포지터리 삭제 불가
GitLab 인스턴스의 컨테이너 레지스트리를 비활성화하고 컨테이너 리포지터리가 있는 프로젝트를 제거하려고하면 다음 오류가 발생합니다:
Errno::ENOENT: No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key
이 경우 다음 단계를 따르세요:
-
gitlab.rb
에서 인스턴스 전체 설정에 대한 컨테이너 레지스트리를 임시로 활성화합니다:gitlab_rails['registry_enabled'] = true
- 변경 사항이 적용되도록 파일을 저장하고 GitLab을 다시 구성합니다.
- 제거를 다시 시도하세요.
일반적인 방법으로 리포지터리를 제거할 수 없는 경우 GitLab Rails 콘솔을 사용하여 프로젝트를 강제로 제거할 수 있습니다:
# 제거하려는 프로젝트의 경로
prj = Project.find_by_full_path(<project_path>)
# 위의 코드는 프로젝트의 컨테이너 레지스트리를 삭제하므로 경로를 재확인해주세요!
if prj.has_container_registry_tags?
prj.container_repositories.each { |p| p.destroy }
end