컨테이너 레지스트리 활성화
- 리눅스 패키지 설치
- 자체 컴파일 설치
컨테이너 레지스트리 도메인 구성
- 기존 GitLab 도메인에 컨테이너 레지스트리 구성
- 자체 도메인을 사용하여 컨테이너 레지스트리 구성
사이트 전체에서 컨테이너 레지스트리 비활성화
사이트 전체에서 새 프로젝트용 컨테이너 레지스트리 비활성화
- 토큰 유효 기간 증가
컨테이너 레지스트리용 스토리지 구성
레지스트리의 내부 포트 변경
프로젝트별 컨테이너 레지스트리 비활성화
GitLab를 인증 엔드포인트로 사용하는 외부 컨테이너 레지스트리
- Linux package installations
- 자체 컴파일 설치
컨테이너 레지스트리 알림 구성
정책 지금 실행
- 프로젝트별 레지스트리 디스크 공간 사용
컨테이너 레지스트리 메타데이터 데이터베이스
컨테이너 레지스트리 가비지 수집
GitLab 및 레지스트리를 별도 노드에서 실행하도록 구성하기 (Linux 패키지 설치)
- 레지스트리 구성
- GitLab 구성
GitLab 컨테이너 레지스트리 아키텍처
- GitLab과 레지스트리 간 통신
서드파티 레지스트리에서의 이전
- Docker Distribution 레지스트리
문제 해결

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

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

next-generation container registry 은 이제 베타 기능으로 Self-managed 인스턴스에서 업그레이드 및 테스트할 수 있습니다. 이 업그레이드된 레지스트리는 온라인 가비지 수집을 지원하며, 중요한 성능 및 신뢰성 개선이 있습니다.

GitLab 컨테이너 레지스트리를 사용하면 모든 프로젝트가 도커 이미지를 저장할 수 있는 공간을 갖게 됩니다.

컨테이너 레지스트리에 대한 자세한 내용은 다음을 참조하세요:

이 문서는 관리자 가이드입니다. GitLab 컨테이너 레지스트리 사용 방법을 알아보려면 사용자 문서를 참조하세요.

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

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

리눅스 패키지 설치

리눅스 패키지를 사용하여 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에서 레지스트리의 설정을 구성해 활성화해야 합니다.
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 재시작은 설정을 변경하더라도 레지스트리를 다시 시작하지 않습니다. 이를 달성하는 방법에 대한 상류 문서를 참조하십시오.

최소한 레지스트리 구성이 다음과 같아야 합니다.

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인 경우, 레지스트리를 구성하려면:

리눅스 패키지 설치를 사용하는 경우 gitlab.rb를 편집하십시오.
자체 컴파일 설치를 사용하는 경우 gitlab.yml을 편집하십시오.

여기서 기존 레지스트리가 수신하는 포트와 다른 포트를 선택해야 하며(기본값은 5000), 그렇지 않으면 충돌이 발생합니다.

리눅스 패키지 (Omnibus)

/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

TLS 인증서 제공 업체가 CA 번들 인증서를 제공하는 경우 이를 TLS 인증서 파일에 추가하십시오.

관리자는 레지스트리를 5678과 같은 임의의 포트에서 수신하도록 할 수 있을지 모릅니다. 그러나 레지스트리와 애플리케이션 서버는 80 및 443 포트에서만 수신하는 AWS 애플리케이션 로드 밸런서 뒤에 있습니다. 사용자가 컨테이너 레지스트리의 docker login 예상을 의존하는 경우, registry_external_url에서 포트 번호를 제거하여 HTTP 또는 HTTPS가 가정되게 만들 수 있습니다. 그런 다음 규칙을 사용하여 로드 밸런서를 레지스트리에서 80 또는 443 포트로 매핑할 수 있습니다. 이것은 사용자가 컨테이너 레지스트리의 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에 의해 자동으로 생성된 인증서도 Linux 패키지 설치에서 지원됩니다.

컨테이너 레지스트리를 https://registry.gitlab.example.com에서 접근할 수 있도록 하려면 다음과 같이 합니다.

Linux 패키지 (Omnibus)

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 이미지 제거는 레지스트리 응용 프로그램이 처리합니다.

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 열고 registry['enable']을 false로 설정합니다:
```
registry['enable'] = false
```
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.

직접 컴파일한 경우 (소스)

/home/git/gitlab/config/gitlab.yml을 열고 registry 항목을 찾아 enabled를 false로 설정합니다:
```
registry:
  enabled: false
```
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.

사이트 전체에서 새 프로젝트용 컨테이너 레지스트리 비활성화

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

Linux 패키지 (Omnibus)

/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_projects_features:
  issues: true
  merge_requests: true
  wiki: true
  snippets: false
  builds: true
  container_registry: false

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

토큰 유효 기간 증가

GitLab에서 컨테이너 레지스트리의 토큰은 5분마다 만료됩니다. 토큰 기간을 증가시키려면:

왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
설정 > CI/CD를 선택합니다.
컨테이너 레지스트리를 확장합니다.
인가 토큰 기간(분)을 업데이트합니다.
변경 사항 저장을 선택합니다.

컨테이너 레지스트리용 스토리지 구성

지원하는 스토리지 백엔드에서 버전 관리를 사용하여 저장 버킷에 저장되는 모든 객체의 비현재 버전을 보존, 검색 및 복원할 수 있습니다. 그러나 이로 인해 더 높은 저장 공간 사용량과 비용이 발생할 수 있습니다. 레지스트리의 작동 방식 때문에 이미지 업로드는 먼저 임시 경로에 저장되고 나중에 최종 위치로 전송됩니다. S3 및 GCS를 포함한 오브젝트 스토리지 백엔드의 경우 이 전송은 복사 후 삭제로 이루어집니다. 버전 관리가 활성화된 경우 삭제된 임시 업로드 아티팩트가 비현재 버전으로 유지되어 저장 버킷 크기가 증가합니다. 비현재 버전이 특정 기간이 경과한 후 삭제되도록 하려면 저장 공급자와 객체 수명주기 정책을 구성해야 합니다.

컨테이너 레지스트리에 저장된 파일이나 객체를 직접 수정하지 마십시오. 레지스트리가 이러한 항목을 쓰거나 삭제하는 것 외에 다른 작업을 수행하면 인스턴스 전체의 데이터 일관성 및 안정성 문제가 발생할 수 있으며 이를 회복할 수 없을 수 있습니다.

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

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

드라이버	설명
`filesystem`	로컬 파일 시스템 상의 경로 사용
`azure`	Microsoft Azure Blob Storage
`gcs`	Google Cloud Storage
`s3`	Amazon Simple Storage Service. 올바른 S3 Permission Scopes로 저장 버킷을 구성해야 합니다.

대부분의 S3 호환 서비스(예: MinIO)는 컨테이너 레지스트리와 함께 작동해야 하지만, 우리는 AWS S3를 위한 지원만 보장합니다. 서드파티 S3 구현의 정확성을 보증할 수 없기 때문에 문제를 디버깅할 수는 있지만 문제가 AWS S3 버킷에서 재현 가능한 경우에만 레지스트리를 수정할 수 있습니다.

다음 드라이버에 대한 지원은 GitLab 16.6에서 폐기 예정되었으며 17.0에서 제거될 예정입니다. 이 변경 사항은 호환성이 깨질 수 있는 중요한 변경 사항입니다.

드라이버	설명
`swift`	OpenStack Swift 객체 스토리지
`oss`	Aliyun OSS

파일 시스템 사용

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

이 경로는 다음에 접근할 수 있습니다:

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

모든 GitLab, 레지스트리 및 웹 서버 사용자는 이 디렉터리에 액세스해야 합니다.

Linux 패키지 (Omnibus)

Linux 패키지 설치의 기본 위치는 /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에서 객체 리포지터리 사용에 대해 자세히 알아보기.

파일 시스템에 저장되지 않은 Docker 이미지는 GitLab에서 백업되지 않습니다. 원하는 경우 오브젝트 스토리지 공급업체와 백업을 활성화하세요.

Linux 패키지 설치를 위한 `s3` 및 `gcs` 저장 드라이버 구성

다음 구성 단계는 s3 및 gcs 저장 드라이버를 위한 것입니다. 다른 저장 드라이버도 지원됩니다.

Linux 패키지 설치를 위해 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를 사용하려면 false로 설정하세요. 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을 재구성합니다.

Linux 패키지 설치를 위해 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은 존재하는 버킷 이름이어야 하며 하위 디렉터리를 포함할 수 없습니다.

다운타임 없이 객체 리포지터리로 마이그레이션

S3 버킷 간 또는 S3 버킷으로 레지스트리 데이터를 복사할 때 AWS DataSync를 사용하면 버킷에 유효하지 않은 메타데이터 개체가 생성됩니다. 자세한 내용은 빈 이름 태그을 참조하세요. 데이터를 S3 버킷으로 이동하려면 AWS CLI sync 작업을 권장합니다.

컨테이너 레지스트리를 중지하지 않고 리포지터리를 마이그레이션하려면 컨테이너 레지스트리를 읽기 전용 모드로 설정하세요. 대규모 인스턴스의 경우, 이 작업은 컨테이너 레지스트리를 어느 정도 동안 읽기 전용 모드로 설정해야 할 수 있습니다. 이 기간 동안에 컨테이너 레지스트리에서는 가져오기는 할 수 있지만 푸시는 할 수 없습니다.

선택 사항: 마이그레이션할 데이터 양을 줄이려면 다운타임 없이 가비지 수집 도구를 실행하세요.
이 예시에서는 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 객체 리포지터리로 이동

리포지터리 드라이버의 기본 구성이 변경될 예정되어 있습니다. GitLab 16.0에서.

기존 파일 시스템이나 다른 객체 리포지터리 제공자에서 Azure 객체 리포지터리로 이동할 때, 레지스트리를 표준 루트 디렉터리를 사용하도록 구성해야 합니다. 레지스트리 구성의 Azure 리포지터리 드라이버 섹션에서 trimlegacyrootprefix: true를 설정하여 구성하세요. 이 구성을 하지 않으면 Azure 리포지터리 드라이버는 마이그레이션된 이미지에 액세스할 수 없게 // 대신에 /를 루트 경로의 첫 번째 섹션으로 사용합니다.

Linux package (Omnibus)

registry['storage'] = {
  'azure' => {
    'accountname' => 'accountname',
    'accountkey' => 'base64encodedaccountkey',
    'container' => 'containername',
    'rootdirectory' => '/azure/virtual/container',
    'trimlegacyrootprefix' => true
  }
}

Self-compiled (source)

storage:
  azure:
    accountname: accountname
    accountkey: base64encodedaccountkey
    container: containername
    rootdirectory: /azure/virtual/container
    trimlegacyrootprefix: true

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

리포지터리 드라이버용 리디렉션 비활성화

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

그러나 내부 호스트에서 사용되는 레지스트리에 대해 이 동작은 원하지 않습니다. 일반적으로 내부 호스트는 공개 서버에 액세스할 수 없습니다. 리디렉션을 비활성화하고 프록시 다운로드로 설정하려면 disable 플래그를 true로 설정하세요. 이렇게 하면 모든 트래픽이 항상 레지스트리 서비스를 통해 전송됩니다. 이것은 보안을 강화(리포지터리 백엔드에 공개적으로 액세스할 수 없으므로 공격 표면이 줄어듦)하지만 성능이 악화되는 결과를 가져옵니다(모든 트래픽이 서비스를 통해 리디렉션되기 때문).

Linux package (Omnibus)

/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을 재구성하여 변경 내용을 적용합니다.

Self-compiled (source)

레지스트리 구성 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 버킷

SSE-S3 또는 SSE-KMS 암호화 기능이 기본적으로 활성화된 S3 버킷에 대해 AWS KMS를 사용하여 서버 측 암호화를 할 수 있습니다. 고객 마스터 키(CMK) 및 SSE-C 암호화는 모든 요청에 암호화 키를 보내야 하기 때문에 지원되지 않습니다.

SSE-S3의 경우, 레지스트리 설정에서 encrypt 옵션을 활성화해야 합니다. 이 작업은 GitLab를 어떻게 설치했는지에 따라 다르게 수행됩니다. 설치 방법에 맞는 지침을 따르세요.

Linux package (Omnibus)

/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을 다시 구성하세요.

Self-compiled (source)

레지스트리 구성 YAML 파일을 편집하세요:

storage:
  s3:
    accesskey: 'AKIAKIAKI'
    secretkey: 'secret123'
    bucket: 'gitlab-registry-bucket-AKIAKIAKI'
    region: 'your-s3-region'
    regionendpoint: 'your-s3-regionendpoint'
    encrypt: true

파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.

리포지터리 제한

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

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

기본적으로 레지스트리 서버는 로컬에서 5000포트에서 수신 대기합니다. 아래 예제에서는 레지스트리의 포트를 5010으로 설정합니다.

Linux package (Omnibus)

/etc/gitlab/gitlab.rb를 열고 registry['registry_http_addr']을 설정하세요:
```
registry['registry_http_addr'] = "localhost:5010"
```
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.

Self-compiled (source)

레지스트리 서버의 구성 파일을 열고 http:addr 값을 편집하세요:
```
http:
  addr: localhost:5010
```
파일을 저장하고 레지스트리 서버를 다시 시작하세요.

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

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

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

GitLab 15.8에서 GitLab에서 제3자 컨테이너 레지스트리 사용이 폐기되었으며 GitLab 16.0에서 지원이 종료되었습니다. GitLab 컨테이너 레지스트리 대신 제3자 컨테이너 레지스트리를 사용해야 하는 경우, 사용 사례에 대해 피드백 이슈 958에서 알려주세요.

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

통합 작업을 위해 외부 레지스트리는 GitLab과의 인증을 위해 JSON 웹 토큰을 사용하도록 구성되어야 합니다. 외부 레지스트리의 런타임 구성에는 다음 항목이 반드시 있어야 합니다:

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 package installations

외부 컨테이너 레지스트리에서 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'] = "http://<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"
   
# Linux 패키지 설치를 위해 커스텀 파일에 registry['internal_key'] 내용을 쓸 수 있도록 선택적으로 정의합니다.
gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
```
각각의 reconfigure 실행마다 registry_key_path에서 지정한 파일이 internal_key에 의해 지정한 내용으로 채워집니다. 파일이 지정되지 않은 경우 Linux 패키지 설치는 기본적으로 /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 알림 문서에서 컨테이너 레지스트리 알림 구성 옵션에 대해 자세히 읽어보세요.

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

Linux package (Omnibus)

Linux 패키지 설치의 알림 엔드포인트를 구성하려면 다음을 수행합니다:

/etc/gitlab/gitlab.rb을 편집합니다:

registry['notifications'] = [
  {
    'name' => 'test_endpoint',
    'url' => 'https://gitlab.example.com/notify',
    'timeout' => '500ms',
    'threshold' => 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
      backoff: 1000

정책 지금 실행

분산 아키텍처를 사용하고 Sidekiq가 다른 노드에서 실행 중인 경우 정책이 작동하지 않습니다. 이를 해결하려면:

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 "#{ps[0]},#{ps[1]},#{ps[2]},#{ps[3]}"
end

정책을 실행하여 이미지 태그를 제거하려면 다음을 실행하세요. GitLab Rails 콘솔:

# 컨테이너 레지스트리를 정리해야 하는 프로젝트의 숫자 ID
P = <project_id>

# 프로젝트에 대한 Developer, Maintainer 또는 Owner 역할을 가진 사용자의 숫자 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

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

Tier: Free, Premium, Ultimate 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 registry-garbage-collect 명령을 우회하세요.

가비지 수집 중에는 이미지를 가져올 수 있지만 이미지를 푸시할 수는 없습니다. 컨테이너 레지스트리는 가비지 수집 기간 동안 읽기 전용으로 유지해야 합니다.

기본적으로 레지스트리 리포지터리 경로는 /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 아래에 파일을 만드세요.

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 플래그를 추가할 수도 있습니다.

가비지 수집 중지

가비지 수집을 중지할 예정인 경우, 다운타임 없는 가비지 수집 실행에 설명된대로 가비지 수집을 매뉴얼으로 실행해야 합니다. 그런 다음, gitlab-ctl을 중단하면 레지스트리 서비스가 다운된 상태로 남을 수 있습니다. 이 경우에는 가비지 수집 프로세스 를 시스템에서 찾아서 gitlab-ctl 명령이 레지스트리 서비스를 다시 시작할 수 있도록 해야 합니다.

또한, 프로세스의 마크 단계에서 진행 상황이나 결과를 저장하는 방법은 없습니다. 뭔가 영구적으로 변경되는 건 블롭이 삭제되기 시작할 때뿐입니다.

지속적인 다운타임 제로 가비지 수집

상태: 베타

메타데이터 데이터베이스로 이전하면 스케줄링 없이 백그라운드에서 가비지 수집을 실행할 수 있습니다. 읽기 전용 모드나 스케줄링이 필요하지 않습니다.

만약 이 베타 기능을 시도하려면 알려진 제한 사항을 검토하세요. 피드백이 있을 경우, 피드백 이슈를 통해 알려 주세요.

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

기본적으로 패키지는 두 서비스가 동일한 노드에서 실행 중이라고 가정합니다. GitLab 및 레지스트리를 별도의 노드에서 실행하려면 Registry와 GitLab를 별도로 구성해야 합니다.

레지스트리 구성

아래에서는 Registry가 GitLab과 별도로 실행되도록 /etc/gitlab/gitlab.rb에 설정해야 하는 구성 옵션을 찾을 수 있습니다:

registry['registry_http_addr'], 기본값 프로그래밍적으로 설정됨. 웹 서버(또는 LB)에서 액세스할 수 있어야 합니다.
registry['token_realm'], 기본값 프로그래밍적으로 설정됨. 일반적으로 GitLab URL인 인증 수행에 사용할 엔드포인트를 지정합니다. 이 엔드포인트는 사용자가 액세스할 수 있어야 합니다.
registry['http_secret'], 임의의 문자열. 클라이언트와 함께 저장될 수 있는 상태를 서명하는 데 사용되는 임의의 데이터 조각입니다.
registry['internal_key'], 기본값 자동으로 생성됨. GitLab이 토큰을 서명하는 데 사용하는 키의 내용입니다. 이 키는 Registry 서버에서 생성되지만 거기서 사용되지는 않습니다.
gitlab_rails['registry_key_path'], 기본값 프로그래밍적으로 설정됨. 이는 internal_key 내용이 디스크에 작성되는 경로입니다.
registry['internal_certificate'], 기본값 자동으로 생성됨. GitLab이 토큰을 서명하는 데 사용하는 인증서의 내용입니다.
registry['rootcertbundle'], 기본값 프로그래밍적으로 설정됨. 인증서의 경로입니다. 이는 internal_certificate 내용이 디스크에 작성되는 경로입니다.
registry['health_storagedriver_enabled'], 기본값 프로그래밍적으로 설정됨. 구성된 스토리지 드라이버의 상태 체크를 활성화할지 구성합니다.
gitlab_rails['registry_issuer'], 기본값. 이 설정은 Registry와 GitLab 간에 동일하게 설정되어야 합니다.

GitLab 구성

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

gitlab_rails['registry_enabled'], true로 설정해야 합니다. 이 설정은 GitLab에게 Registry API 요청을 허용해야 함을 나타냅니다.
gitlab_rails['registry_api_url'], 기본값 프로그래밍적으로 설정됨. 이는 사용자가 상호 작용할 필요가 없는 내부적으로 사용되는 Registry URL입니다. registry['registry_http_addr']와 함께 scheme입니다.
gitlab_rails['registry_host'], 예를 들어 registry.gitlab.example입니다. 이는 scheme을 제외한 Registry 엔드포인트로, 최종 사용자에게 표시되는 주소입니다.
gitlab_rails['registry_port']. 최종 사용자에게 표시되는 Registry 엔드포인트 포트입니다.
gitlab_rails['registry_issuer']는 Registry 구성과 일치해야 합니다.
gitlab_rails['registry_key_path'], Registry 측의 인증서와 일치하는 키의 경로입니다.
gitlab_rails['internal_key'], GitLab이 토큰을 서명하는 데 사용하는 키의 내용입니다.

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

GitLab 레지스트리는 사용자가 자체 Docker 이미지를 저장하는 데 사용됩니다. 이로 인해 레지스트리는 클라이언트를 대상으로 하므로 웹 서버(또는 로드 밸런서, LB)에서 직접 노출됩니다.

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

사용자가 클라이언트에서 docker login registry.gitlab.example를 실행합니다. 이는 443 포트에서 웹 서버(또는 LB)에 도달합니다.
웹 서버가 레지스트리 백엔드 풀(기본적으로 5000 포트를 사용)에 연결합니다. 사용자가 유효한 토큰을 제공하지 않았기 때문에, 레지스트리는 401 HTTP 코드를 반환하고 URL을 반환합니다(Registry 구성의 token_realm). 이는 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분)의 네임스페이스 제한 토큰이 생성되고 비공개 키로 서명됩니다. 레지스트리는 그 서명이 구성된 레지스트리 인증서와 일치하는지 확인하고 작업을 허용합니다. GitLab 백그라운드 작업 처리(Sidekiq을 통해)도 레지스트리와 상호 작용합니다. 이러한 작업은 이미지 삭제를 처리하기 위해 레지스트리와 직접 대화합니다.

서드파티 레지스트리에서의 이전

GitLab에서 외부 컨테이너 레지스트리 사용은 GitLab 15.8에서 폐기되었으며 지원 종료는 GitLab 16.0에서 발생했습니다. 자세한 내용은 폐기 알림을 참조하십시오.

GitLab 16.0에서 통합은 비활성화되지는 않았지만, 디버깅 및 문제 해결 지원은 더는 제공되지 않습니다. 또한, 통합은 더 이상 개발되거나 새로운 기능으로 확장되지 않습니다. 새로운 GitLab 컨테이너 레지스트리 버전이 자기 관리형 시스템용으로 사용 가능한 이후에는, 외부 레지스트리 기능이 완전히 제거될 수 있습니다 (에픽 5521 참조).

본 섹션에서는 관리자들이 세 번째 파티 레지스트리에서 GitLab 컨테이너 레지스트리로 이전하는 데 도움이 되는 지침을 제공합니다. 여기에 나열되지 않은 경우 사용 중인 세 번째 파티 컨테이너 레지스트리에 대한 사용 사례를 피드백 이슈에서 설명할 수 있습니다.

아래 제공된 모든 지시 사항에 대해 먼저 테스트 환경에서 시도해 보아야 합니다. 모든 것이 예상대로 작동하는지 확인한 후에 제품 환경에서 재현하십시오.

Docker Distribution 레지스트리

Docker Distribution 레지스트리는 CNCF에 기증되어 이제 Distribution 레지스트리로 알려지고 있습니다. 이 레지스트리는 GitLab 컨테이너 레지스트리가 기반으로 한 오픈소스 구현체입니다. GitLab 컨테이너 레지스트리는 Distribution 레지스트리가 제공하는 기본 기능과 호환되며, 모든 지원되는 리포지터리 백엔드를 포함한 기능을 제공합니다. GitLab 컨테이너 레지스트리로 마이그레이션하려면 이 페이지에 있는 지침을 따르고, Distribution 레지스트리와 동일한 리포지터리 백엔드를 사용하십시오. GitLab 컨테이너 레지스트리는 Distribution 레지스트리에 사용 중인 구성과 동일하게 수용해야 합니다.

문제 해결

다음 섹션에 들어가기 전에 기본 문제 해결 사항을 확인해 보세요:

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은 컨테이너 레지스트리에서 자체 서명된 인증서를 Out-of-the-box로 지원하지는 않지만, 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"]

이에 대한 추가 정보: 이슈 18239.

‘token signed by untrusted key’와 함께 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은 레지스트리의 인증 토큰을 암호화하기 위해 인증서 키 쌍의 두 측면의 내용을 사용합니다. 이 메시지는 이러한 내용이 일치하지 않음을 의미합니다.

사용 중인 파일을 확인하십시오.

/var/opt/gitlab/registry/config.yml에서 auth:를 검색하십시오(다음 줄 포함하여 6줄).

## Container registry certificate
   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를 검색하십시오(다음 줄 포함하여 9줄).

## Container registry key
   registry:
     enabled: true
     host: gitlab.company.com
     port: 4567
     api_url: http://127.0.0.1:5000 # internal address to the registry, is used by GitLab to directly communicate with 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:

이러한 openssl 명령의 출력은 해당 인증서 키 쌍이 일치함을 증명해야 합니다:

/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에 존재하는 경우,이를 사용하여 다시 생성됩니다. 새로운 쌍을 생성하려면 gitlab-ctl reconfigure를 실행하기 전에 /etc/gitlab/gitlab-secrets.json에서 ‘registry’ 섹션을 삭제하십시오.

자체 서명된 쌍으로 자동으로 생성된 인증서 키 쌍을 재정의하고 내용이 일치하는지 확인한 경우, /etc/gitlab/gitlab-secrets.json에서 ‘registry’ 섹션을 삭제하고 gitlab-ctl reconfigure를 실행할 수 있습니다.

AWS S3 및 GitLab 레지스트리 오류

AWS S3를 GitLab 레지스트리와 함께 사용할 때 큰 이미지를 푸시하는 동안 오류가 발생할 수 있습니다. 다음과 같은 레지스트리 로그를 확인하세요.

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) 사이의 값을 시작으로 설정하세요.

Linux package (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집하세요:

registry['storage'] = {
  's3' => {
    'accesskey' => 'AKIAKIAKI',
    'secretkey' => 'secret123',
    'bucket'    => 'gitlab-registry-bucket-AKIAKIAKI',
    'chunksize' => 25000000
  }
}

파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.

Self-compiled (소스)

config/gitlab.yml 파일을 편집하세요:

storage:
  s3:
    accesskey: 'AKIAKIAKI'
    secretkey: 'secret123'
    bucket: 'gitlab-registry-bucket-AKIAKIAKI'
    chunksize: 25000000

파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.

이전 Docker 클라이언트 지원

GitLab과 함께 제공되는 Docker 컨테이너 레지스트리는 기본적으로 스키마1 매니페스트를 비활성화합니다. 그러나 이전 버전의 Docker 클라이언트(1.9 이하)를 사용하는 경우 이미지를 푸시하는 동안 오류가 발생할 수 있습니다. 자세한 내용은 이슈 4145를 참조하세요.

역호환성을 위한 구성 옵션을 추가할 수 있습니다.

Linux package (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집하세요:

registry['compatibility_schema1_enabled'] = true

파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.

Self-compiled (소스)

레지스트리를 설치할 때 생성한 YAML 구성 파일을 편집하고 다음 스니펫을 추가하세요:
```
compatibility:
    schema1:
        enabled: true
```
변경 사항이 적용되도록 레지스트리를 다시 시작하세요.

Docker 연결 오류

그룹, 프로젝트 또는 브랜치 이름에 특수 문자가 포함되어 있는 경우 도커 연결 오류가 발생할 수 있습니다. 특수 문자로는 다음이 포함됩니다:

선행 밑줄
후행 하이픈/대시
이중 하이픈/대시

이를 해결하기 위해 그룹 경로를 변경, 프로젝트 경로를 변경하거나 브랜치 이름을 변경할 수 있습니다. 또 다른 옵션은 인스턴스 수준에서 이를 방지하기 위해 푸시 규칙을 생성하는 것입니다.

이미지 푸시 오류

이미지를 푸시하려고 시도하는 중에 오류나 “다시 시도 중” 루프가 발생하지만 docker login은 정상적으로 작동하는 경우, NGINX에 의해 레지스트리로 전달된 헤더에 문제가 있는 것으로 보입니다. 기본 권장 NGINX 구성은 이를 처리해야 하지만 SSL이 제3자 역방향 프록시로 오프로드되는 사용자 정의 설정에서 발생할 수 있습니다.

이 문제는 Docker 프로젝트 이슈에서 논의되었으며, 레지스트리에서 상대적인 URL을 사용하도록 설정하는 것이 간단한 해결책일 수 있습니다.

Linux package (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집하세요:

registry['env'] = {
  "REGISTRY_HTTP_RELATIVEURLS" => true
}

파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.

Self-compiled (소스)

레지스트리를 설치할 때 생성한 YAML 구성 파일을 편집하고 다음 스니펫을 추가하세요:
```
http:
    relativeurls: true
```
변경 사항이 적용되도록 파일을 저장하고 GitLab을 다시 시작하세요.

레지스트리 디버그 서버 활성화

레지스트리 디버그 서버를 사용하여 문제를 진단할 수 있습니다. 디버그 엔드포인트를 사용하여 메트릭 및 상태를 모니터링하고 프로파일링할 수 있습니다.

디버그 엔드포인트에서는 민감한 정보가 사용 가능할 수 있습니다. 운영 환경에서는 디버그 엔드포인트에 대한 액세스를 제어해야 합니다.

gitlab.rb 구성에서 레지스트리 디버그 주소를 설정하여 디버그 서버를 활성화할 수 있습니다.

registry['debug_addr'] = "localhost:5001"

설정을 추가한 후 GitLab을 다시 구성하여 변경 사항을 적용하세요.

curl을 사용하여 디버그 서버에서 디버그 출력을 요청할 수 있습니다.

curl "localhost:5001/debug/health"
curl "localhost:5001/debug/vars"

구버전 스키마 v1 Docker 이미지 액세스

스키마 V1 이미지 매니페스트를 포함한 Docker 레지스트리 API V1의 지원은:

GitLab 컨테이너 레지스트리에서 이제 더 이상 v1 이미지를 푸시하거나 풀 수 없습니다.

GitLab 컨테이너 레지스트리에 v1 이미지가 있지만 GitLab 13.9 업그레이드 전에 이를 업그레이드하지 않은 경우, 이러한 이미지에 더 이상 액세스할 수 없습니다. 이러한 이미지를 풀어 오류가 발생하면 다음 오류가 표시됩니다.

Error response from daemon: manifest invalid: Schema 1 manifest not supported

Self-managed GitLab 인스턴스의 경우 GitLab 컨테이너 레지스트리를 v3.0.0-gitlab보다 낮은 버전으로 일시적으로 다운그레이드하여 이러한 이미지에 다시 액세스할 수 있습니다. 다음 단계에 따라 이 이미지에 액세스하세요:

컨테이너 레지스트리를 v2.13.1-gitlab로 다운그레이드합니다.
v1 이미지를 업그레이드합니다.
컨테이너 레지스트리 다운그레이드를 되돌립니다.

이미지 업그레이드 과정에서 레지스트리를 읽기 전용 모드로 설정할 필요는 없습니다. v3.0.0-gitlab 이후에 소개된 새로운 기능을 의존하지 않는지 확인하세요. 이러한 기능은 업그레이드 과정 중에 사용할 수 없습니다. 자세한 내용은 완전한 레지스트리 변경로그를 참조하세요.

다음 섹션에서 각 설치 방법에 대한 추가 세부 정보를 제공합니다.

Helm 차트 (Kubernetes)

Helm 차트 설치에 대해:

image.tag 구성 매개변수를 v2.13.1-gitlab로 재정의하세요.
다시 시작하세요.
이미지 업그레이드 단계를 수행하세요.
이전 값으로 image.tag 매개변수를 복구하세요.

기타 레지스트리 구성 변경이 필요하지 않습니다.

Linux package (Omnibus)

Linux 패키지 설치에 대해:

v3.0.0-gitlab보다 오래된 버전을 포함하는 GitLab 13.9+용 레지스트리 바이너리를 일시적으로 대체하세요. 이를 위해 GitLab 컨테이너 레지스트리의 이전 버전(예: v2.13.1-gitlab) Docker 이미지를 가져와서 해당 이미지 내의 /bin/registry에서 찾을 수 있는 registry 바이너리를 가져옵니다:
```
id=$(docker create registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v2.13.1-gitlab)
docker cp $id:/bin/registry registry-2.13.1-gitlab
docker rm $id
```
Linux 패키지에 포함된 원래 바이너리를 백업한 후(registry-2.13.1-gitlab) 바이너리를 /opt/gitlab/embedded/bin/registry에 대체하세요. 바이너리를 대체하기 전에 레지스트리 서비스를 중지하고 바이너리를 대체한 후 바로 시작하세요. 레지스트리 구성 변경이 필요하지 않습니다.

Self-compiled (소스)

registry 바이너리를 찾아서 Linux 패키지 설치에 대한 명령대로 일시적으로 대체하세요. 이미지 업그레이드 단계를 수행한 후 원래의 레지스트리 바이너리를 복구하세요.

이미지 업그레이드

Docker에서 제안하는 단계를 따라 v1 이미지를 업그레이드하세요. 가장 간단한 옵션은 해당 이미지를 끌어와서 다시 레지스트리에 푸시하는 것인데, 이때 v1.12 이상의 Docker 클라이언트 버전을 사용하세요. Docker는 이미지를 레지스트리에 푸시하기 전에 자동으로 이미지를 변환합니다. 완료되면 이제 모든 v1 이미지가 v2 이미지로 사용 가능해집니다.

이름이 비어있는 태그

AWWS DataSync를 사용하여 레지스트리 데이터를 S3 버킷으로 또는 버킷 간에 복사하는 경우, 대상 버킷의 각 컨테이너 리포지터리의 루트 경로에 빈 메타데이터 개체가 생성됩니다. 이렇게 되면 레지스트리는 GitLab UI 및 API에 이름이 지정되지 않은 태그로 표시합니다. 자세한 내용은 이 이슈를 참조하세요.

이를 해결하려면 두 가지 방법 중 하나를 선택할 수 있습니다:

AWS CLI의 rm 명령을 사용하여 영향을 받는 각 리포지터리의 루트에서 빈 개체를 제거하세요. 반드시 /를 주의깊게 확인하고 --recursive 옵션을 사용하지 않도록 주의하세요:
```
aws s3 rm s3://<bucket>/docker/registry/v2/repositories/<리포지터리 경로>/
```
AWS CLI의 sync 명령을 사용하여 레지스트리 데이터를 새 버킷으로 복사하고 레지스트리를 사용하도록 구성하세요. 이렇게 하면 빈 개체가 남겨집니다.

고급 문제 해결

S3 설정 문제를 진단하기 위해 구체적인 예제를 사용합니다.

정리 정책 조사

정리 정책이 태그를 삭제했는지 또는 삭제하지 않았는지 확신이 없다면 Rails 콘솔에서 아래 스크립트를 실행하여 정책을 한 줄씩 실행하세요. 이를 통해 정책과 관련된 문제를 진단할 수 있습니다.

repo = ContainerRepository.find(<프로젝트_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를 통해 이뤄지기 때문에 비밀키를 알고 있더라도 트래픽을 쉽게 해독하기가 어렵습니다. 대신 어떻게 할 수 있을까요?

한 가지 방법은 보안 등록기를 사용하여 HTTPS를 비활성화하는 것입니다. 이것은 보안 허젬을 만들 수 있으며 로컬 테스트에만 추천됩니다. 이를 수행할 수 없거나 수행하지 않으려는 경우 다른 방법이 있습니다: Man-in-the-Middle Proxy인 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

성공적으로 완료되면 출력에 인증서가 추가되었다는 내용이 표시됩니다:

Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....done.

인증서가 올바르게 설치되었는지 확인하려면 다음을 실행하세요:

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="https://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

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

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

리눅스 패키지 설치

자체 컴파일 설치

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

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

자체 도메인을 사용하여 컨테이너 레지스트리 구성

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

사이트 전체에서 새 프로젝트용 컨테이너 레지스트리 비활성화

토큰 유효 기간 증가

컨테이너 레지스트리용 스토리지 구성

파일 시스템 사용

객체 리포지터리 사용

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

직접 컴파일 설치

다운타임 없이 객체 리포지터리로 마이그레이션

Azure 객체 리포지터리로 이동

리포지터리 드라이버용 리디렉션 비활성화

암호화된 S3 버킷

리포지터리 제한

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

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

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

Linux package installations

자체 컴파일 설치

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

정책 지금 실행

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

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

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

콘텐츠 기반 레이어 이해

참조되지 않는 레이어 제거

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

다운타임 없는 가비지 수집 실행

일정에 따른 가비지 수집 실행

가비지 수집 중지

지속적인 다운타임 제로 가비지 수집

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

레지스트리 구성

GitLab 구성

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

GitLab과 레지스트리 간 통신

서드파티 레지스트리에서의 이전

Docker Distribution 레지스트리

문제 해결

컨테이너 레지스트리에서 자체 서명된 인증서 사용

‘token signed by untrusted key’와 함께 Docker 로그인 시도 실패

AWS S3 및 GitLab 레지스트리 오류

이전 Docker 클라이언트 지원

Docker 연결 오류

이미지 푸시 오류

레지스트리 디버그 서버 활성화

구버전 스키마 v1 Docker 이미지 액세스

이미지 업그레이드

이름이 비어있는 태그

고급 문제 해결

정리 정책 조사

푸시 중 예기치 않은 403 오류

mitmproxy

프록시를 사용하여 Docker 데몬 실행

Docker 클라이언트 실행

gitlab-registry.key가 누락되어 컨테이너 리포지터리 삭제가 불가능한 문제

도움말

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

도움받기

Linux 패키지 설치를 위한 `s3` 및 `gcs` 저장 드라이버 구성

`gitlab-registry.key`가 누락되어 컨테이너 리포지터리 삭제가 불가능한 문제