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

Tier: Free, Premium, Ultimate Offering: Self-Managed
note
차세대 컨테이너 레지스트리는 이제 베타 기능으로 Self-Managed형 인스턴스에서 업그레이드 및 테스트할 수 있습니다. 이 업그레이드된 레지스트리는 온라인 가비지 수집을 지원하며, 상당한 성능 및 신뢰성 향상이 있습니다.

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

Distribution Registry에 대한 자세한 내용은 다음을 참조하세요:

이 문서는 관리자 가이드입니다. GitLab 컨테이너 레지스트리를 사용하는 방법에 대해서는 사용자 설명서를 참조하십시오.

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

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

Linux 패키지 설치

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

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

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

컨테이너 레지스트리는 기본적으로 HTTPS에서 작동합니다. HTTP를 사용할 수도 있지만 권장되지 않으며, 이에 대한 설명은 이 문서의 범위를 벗어나므로 포함되지 않습니다.

자체 컴파일된 설치

GitLab 설치를 자체 컴파일한 경우:

  1. 설치 중 GitLab 버전에 해당하는 이미지를 사용하여 레지스트리를 배포해야 합니다 (예: registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab)
  2. 설치가 완료된 후, 해당 레지스트리를 활성화하려면 gitlab.yml에서 레지스트리 설정을 구성해야 합니다.
  3. 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
caution
auth가 설정되지 않은 경우 사용자는 인증 없이 Docker 이미지를 가져올 수 있습니다.

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

레지스트리의 외부 도메인을 다음 중 하나의 방법으로 구성할 수 있습니다:

컨테이너 레지스트리는 TLS 인증서가 필요하므로 비용이 발생할 수 있습니다.

첫 번째 구성 전에 이를 고려하십시오.

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

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

GitLab 도메인이 https://gitlab.example.com이고 외부 세계로 나가는 포트가 5050이라면, 이렇게 컨테이너 레지스트리를 구성할 수 있습니다:

  • Linux 패키지 설치를 사용하는 경우 gitlab.rb를 편집합니다.
  • 자체 컴파일된 설치를 사용하는 경우 gitlab.yml를 편집합니다.

레지스트리가 기본적으로 사용하는 5000 포트와 중복되지 않는 포트를 선택해야 합니다. 그렇지 않으면 충돌이 발생할 수 있습니다.

note
호스트 및 컨테이너 방화벽 규칙은 registry_external_url 행 하단에 나열된 포트를 통해 들어오는 트래픽을 허용하도록 구성되어야 합니다. 이때의 포트는 gitlab_rails['registry_port'] (기본값 5000) 아래에 나열된 것이 아니라 registry_external_url 행 하단에 나열된 것입니다.
Linux 패키지 (Omnibus)
  1. /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"
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성하세요.

  3. 다음 명령을 사용하여 유효성을 검사합니다.

    openssl s_client -showcerts -servername gitlab.example.com -connect gitlab.example.com:5050 > cacert.pem
    

인증서 제공 업체가 CA 번들 인증서를 제공하는 경우 이를 TLS 인증서 파일에 추가하십시오. 관리자는 레지스트리가 5678과 같은 임의의 포트에서 수신하도록 할 수 있습니다. 그러나 레지스트리 및 응용 프로그램 서버는 80443 포트만 수신하는 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
자체 컴파일 (원본)
  1. /home/git/gitlab/config/gitlab.yml을 열고 registry 항목을 찾아 다음과 같이 구성하세요:

    registry:
      enabled: true
      host: gitlab.example.com
      port: 5050
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작하세요.
  3. NGINX에서도 관련 변경사항을 적용하세요(도메인, 포트, TLS 인증서 경로).

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

docker login gitlab.example.com:5050

자체 도메인 하에 컨테이너 레지스트리 구성

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

매뉴얼으로 생성된 SSL 인증서뿐만 아니라 Let’s Encrypt에 의해 자동으로 생성된 인증서도 리눅스 패키지 설치에서 지원됩니다.

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

리눅스 패키지 (Omnibus)
  1. 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.*
    
  2. TLS 인증서가 준비되면 /etc/gitlab/gitlab.rb를 편집합니다:

    registry_external_url 'https://registry.gitlab.example.com'
    

    registry_external_url은 HTTPS로 수신 대기하고 있습니다.

  3. 파일을 저장하고 변경 사항이 적용되도록 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"
자체 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 열고 registry 항목을 찾아 다음 설정으로 구성합니다:

    registry:
      enabled: true
      host: registry.gitlab.example.com
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.
  3. NGINX에서도 관련 변경 사항(도메인, 포트, TLS 인증서 경로)을 수행합니다.

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

docker login registry.gitlab.example.com

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

이러한 단계를 따라 레지스트리를 비활성화하면 기존의 Docker 이미지는 제거되지 않습니다. Docker 이미지 제거는 레지스트리 응용 프로그램 자체에서 처리됩니다.

리눅스 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb를 열고 registry['enable']false로 설정합니다:

    registry['enable'] = false
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.

자체 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 열고 enabledfalse로 설정합니다:

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

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

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

리눅스 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb를 편집하고 다음 라인을 추가합니다:

    gitlab_rails['gitlab_default_projects_features_container_registry'] = false
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.

자체 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 열고 default_projects_features 항목을 찾아 container_registryfalse로 설정합니다:

    ## Default project features settings
    default_projects_features:
      issues: true
      merge_requests: true
      wiki: true
      snippets: false
      builds: true
      container_registry: false
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.

토큰 기간 증가

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

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

컨테이너 레지스트리의 리포지터리 구성

note
지원하는 리포지터리 백엔드에서는 버전 관리를 사용하여 버킷에 저장된 모든 객체의 이전 버전을 보존, 검색 및 복원할 수 있습니다. 그러나 이렇게 하면 저장 공간 사용량과 비용이 증가할 수 있습니다. 레지스트리 작업 방식 때문에 이미지 업로드가 먼저 임시 경로에 저장되고 그런 다음 최종 위치로 이동됩니다. S3 및 GCS와 같은 객체 리포지터리 백엔드의 경우, 이 전송은 삭제를 따라하는 복사로 달성됩니다. 객체 버전 관리가 활성화된 경우 삭제된 이러한 임시 업로드 아티팩트는 비현재 버전으로 유지되어 저장 버킷 크기가 증가합니다. 비현재 버전이 일정 기간 후에 삭제되도록 보장하려면 리포지터리 제공업체와 객체 수명주기 정책을 구성해야 합니다.
caution
컨테이너 레지스트리에 의해 저장된 파일이나 객체를 직접 수정하지 마십시오. 레지스트리가 이러한 항목을 쓰거나 삭제하지 않은 경우, 복구가 불가능한 인스턴스 전체의 데이터 일관성 및 안정성 문제가 발생할 수 있습니다.

컨테이너 레지스트리는 다양한 리포지터리 백엔드를 사용하도록 구성할 수 있습니다. 기본적으로 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 버킷에서 재현되기 전에는 레지스트리를 수정할 수 없습니다.

caution
다음 드라이버에 대한 지원은 GitLab 16.6에서 더 이상 지원되지 않으며, 17.0에서 제거될 예정입니다. 이 변경 사항은 판단적인 변경입니다.
드라이버 설명
swift OpenStack Swift Object Storage
oss Aliyun OSS

파일 시스템 사용

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

이 경로는 다음에 액세스할 수 있습니다:

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

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

Linux 패키지 (Omnibus)

리눅스 패키지 설치의 기본 이미지 저장 위치는 /var/opt/gitlab/gitlab-rails/shared/registry입니다. 변경하려면:

  1. /etc/gitlab/gitlab.rb를 편집하세요:

    gitlab_rails['registry_path'] = "/path/to/registry/storage"
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성합니다.

자체 컴파일 (소스)

자체 컴파일 설치의 기본 이미지 저장 위치는 /home/git/gitlab/shared/registry입니다. 변경하려면:

  1. /home/git/gitlab/config/gitlab.yml을 열고 registry 항목을 찾아 path 설정을 변경하세요:

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

객체 스토리지 사용

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

GitLab에서 객체 스토리지 사용에 대해 자세히 알아보기.

caution
파일 시스템에 저장되지 않은 Docker 이미지는 GitLab에서 백업하지 않습니다. 필요한 경우 객체 스토리지 제공업체와 백업을 활성화하세요.

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

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

리눅스 패키지 설치를 위해 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 역할을 사용하고 accesskeysecretkey를 생략하세요. 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은 존재하는 버킷 이름이어야 하며 하위 디렉터리를 포함할 수 없습니다.
    • pathstylehost/bucket_name/object 스타일 경로 대신 bucket_name.host/object를 사용하도록 true로 설정하세요. AWS S3를 위해 false로 설정하세요.

    S3 API에서의 503 오류를 피하기 위해 S3 연결의 요청 속도 제한을 설정할 수 있습니다. 이를 위해 maxrequestspersecondS3 요청 속도 임계값 내의 숫자로 설정하세요:

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

가동 중지 없이 객체 스토리지로 이동

caution
S3 버킷 간에 레지스트리 데이터를 복사하면 버킷에 잘못된 메타데이터 객체가 생성됩니다. 자세한 내용은 빈 이름 태그을 참조하세요. S3 버킷으로 데이터를 이동하려면 컨테이너 레지스트리를 읽기 전용 모드로 설정하세요. 대규모 인스턴스의 경우 컨테이너 레지스트리가 어느 정도의 시간 동안 읽기 전용 모드로 설정되어야 할 수 있습니다. 이 기간 동안 컨테이너 레지스트리에서 가져올 수는 있지만 푸시할 수는 없습니다.
  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의 cpsync 명령을 사용하세요. docker 폴더를 버킷의 최상위 폴더로 유지하세요.

    sudo aws --endpoint-url https://your-object-storage-backend.com s3 sync registry s3://mybucket
    
    note
    많은 양의 데이터가 있는 경우 병렬 동기화 작업을 실행하여 성능을 개선할 수 있습니다.
  4. 컨테이너 레지스트리를 읽기 전용으로 설정하고 GitLab을 다시 구성하세요.
  5. 초기 데이터 로드 이후의 변경 사항을 S3 버킷에 동기화하고 목적지 버킷에만 존재하는 파일을 삭제하세요:

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

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

    caution
    --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. 변경 사항이 적용되도록 레지스트리를 다시 읽기-쓰기 모드로 설정하고 GitLab을 다시 구성하세요.

Azure Object Storage로 이동

  • 저장 드라이버의 기본 구성은 GitLab 16.0에서 변경될 예정입니다.

기존 파일 시스템이나 다른 오브젝트 스토리지 공급 업체에서 Azure Object Storage로 이동할 때, 레지스트리를 표준 루트 디렉터리를 사용하도록 구성해야 합니다. 레지스트리 구성의 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 섹션에서 realm의 다른 값을 설정할 수 있습니다(예: Azure Government Cloud의 경우 core.usgovcloudapi.net).

스토리지 드라이버의 리다이렉트 비활성화

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

그러나 이 동작은 일반적으로 공용 서버에 액세스할 수 없는 내부 호스트에서 사용되는 레지스트리에는 원하지 않는 동작입니다. 리디렉트를 비활성화하고 프록시 다운로드를 위해 disable 플래그를 다음과 같이 true로 설정하세요. 이는 모든 트래픽이 항상 레지스트리 서비스를 통해 전달되도록 만듭니다. 이는 보안이 향상되었지만(스토리지 백엔드가 공개적으로 접근할 수 없기 때문에 공격 표면이 줄어듦), 성능이 저하됩니다(모든 트래픽이 서비스를 통해 리디렉션됨).

Linux package (Omnibus)
  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'
      },
      'redirect' => {
        'disable' => true
      }
    }
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.

Self-compiled (source)
  1. 레지스트리 구성 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
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재시작하세요.

암호화된 S3 버킷

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

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

Linux package (Omnibus)
  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',
        'encrypt' => true
      }
    }
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.

Self-compiled (source)
  1. 레지스트리 구성 YAML 파일을 편집하세요:

    storage:
      s3:
        accesskey: 'AKIAKIAKI'
        secretkey: 'secret123'
        bucket: 'gitlab-registry-bucket-AKIAKIAKI'
        region: 'your-s3-region'
        regionendpoint: 'your-s3-regionendpoint'
        encrypt: true
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재시작하세요.

스토리지 제한

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

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

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

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 열고 registry['registry_http_addr']를 설정하세요:

    registry['registry_http_addr'] = "localhost:5010"
    
  2. 파일을 저장하고 변경 사항이 적용되도록 GitLab 재구성하세요.

Self-compiled (source)
  1. 레지스트리 서버의 구성 파일을 열고 http:addr 값을 편집하세요:

    http:
      addr: localhost:5010
    
  2. 파일을 저장하고 레지스트리 서버를 다시 시작하세요.

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

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

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

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

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

통합이 작동하려면 외부 레지스트리가 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을 인증 엔드포인트로 사용할 수 있습니다.

  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'] = "https://<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"
       
    # 리눅스 패키지 설치를 위해 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로 지정하고 채웁니다.

  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 Registry 알림 설명서에서 컨테이너 레지스트리 알림 구성 옵션에 대해 자세히 알아보세요.

caution
threshold 매개변수에 대한 지원이 GitLab 17.0에서 폐지되었으며, 18.0에서 제거가 계획되어 있습니다. 대신 maxretries를 사용하세요.

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

:::Tabs

리눅스 패키지 (Omnibus)

리눅스 패키지 설치용 알림 엔드포인트를 구성하려면 다음을 수행하세요:

  1. /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"]
        }
      }
    ]
    
  2. 파일을 저장하고 변경 사항이 적용되도록 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

정책 정리 지금 실행하기

caution
분산 아키텍처를 사용하고 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 = <프로젝트 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

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

Tier: Free, Premium, Ultimate
Offering: Self-Managed
Status: Beta

메타데이터 데이터베이스를 사용하면 온라인 가비지 수집과 같은 다양한 레지스트리 기능이 가능해지며, 다양한 레지스트리 작업의 효율성이 증가합니다. 자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스 페이지를 참조하십시오.

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

note

Amazon S3 Lifecycle과 같은 오브젝트 스토리지 제공 업체의 보존 정책은 객체가 제대로 삭제되지 못하도록 할 수 있습니다.

컨테이너 레지스트리는 상당량의 저장 공간을 사용할 수 있으며, 저장 공간 사용량을 줄이려면 희망할 수 있습니다. 나열된 옵션 중에서 태그 삭제가 가장 효과적인 옵션입니다. 그러나 태그 삭제만으로는 이미지 레이어를 삭제하지 않고 기본 이미지 매니페스트를 태그 해제만 합니다.

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

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

caution

이 명령은 가비지 수집 전에 컨테이너 레지스트리를 종료하고, 가비지 수집이 완료된 후에만 다시 시작합니다. 다운타임을 피하려면 매뉴얼으로 컨테이너 레지스트리를 읽기 전용 모드로 설정하고 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입니다.

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

  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
    

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

이상적으로는 레지스트리 사용이 없는 시간에 매주 정기적으로 레지스트리의 가비지 수집을 실행하고 싶을 것입니다. 가장 간단한 방법은 매주 한 번 주간에 주기적으로 실행되는 크론탭 작업을 추가하는 것입니다.

/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 명령으로 레지스트리 서비스를 다시 실행할 수 있어야합니다.

또한 프로세스의 마크 단계 중에 진행 상황이나 결과를 저장할 수는 없습니다. 실제로 삭제가 시작되기 전에는 영구적인 작업이 수행되지 않습니다.

지속적인 영구 다운타임 가비지 수집

Status: Beta

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

note

Beta 기능을 사용해보고 싶다면 알려진 제한 사항을 검토해야 합니다. 피드백이 있다면 피드백 이슈에 알려주십시오.

별도 노드에서 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)에 직접 노출됩니다.

GitLab Registry diagram

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

  1. 사용자가 클라이언트에서 docker login registry.gitlab.example를 실행합니다. 이는 포트 443에서 웹 서버(또는 LB)에 도달합니다.
  2. 웹 서버는 레지스트리 백엔드 풀(기본적으로 포트 5000을 사용)에 연결합니다. 사용자가 유효한 토큰 제공하지 않았기 때문에, 레지스트리는 401 HTTP 코드와 사용자가 토큰을 받을 URL인 token_realm(레지스트리 구성에서)을 반환합니다. 이 URL은 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분)의 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에 사용하는 구성과 동일하게 허용해야 합니다.

문제 해결

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

  1. Docker 클라이언트와 GitLab 서버의 시스템 클록이 동기화되었는지 확인하세요 (예: NTP를 통해).

  2. S3를 백업으로 사용하는 경우, IAM 권한과 S3 자격 증명(지역 포함)이 올바른지 다시 확인하세요. 자세한 내용은 샘플 IAM 정책을 참조하세요.

  3. 레지스트리 로그(예: /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) 사이의 값으로 시작하세요.

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb을 편집하세요:

    registry['storage'] = {
      's3' => {
        'accesskey' => 'AKIAKIAKI',
        'secretkey' => 'secret123',
        'bucket'    => 'gitlab-registry-bucket-AKIAKIAKI',
        'chunksize' => 25000000
      }
    }
    
  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab 다시 구성을 실행하세요.

소스에서 직접 컴파일한 경우
  1. config/gitlab.yml을 편집하세요:

    storage:
      s3:
        accesskey: 'AKIAKIAKI'
        secretkey: 'secret123'
        bucket: 'gitlab-registry-bucket-AKIAKIAKI'
        chunksize: 25000000
    
  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 시작하십시오.

이전 버전의 Docker 클라이언트 지원

GitLab과 함께 제공되는 Docker 컨테이너 레지스트리는 기본적으로 schema1 manifest를 비활성화합니다. 여전히 이전 버전의 Docker 클라이언트(1.9 이하)를 사용 중이라면 이미지를 푸시하는 중에 오류가 발생할 수 있습니다. 자세한 내용은 이슈 4145를 확인하세요.

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

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    registry['compatibility_schema1_enabled'] = true
    
  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 구성하십시오.

Self-compiled (source)
  1. 레지스트리를 배포할 때 생성한 YAML 구성 파일을 편집합니다. 다음 스니펫을 추가합니다:

    compatibility:
        schema1:
            enabled: true
    
  2. 변경 사항이 적용되려면 레지스트리를 다시 시작하십시오.

Docker 연결 오류

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

  • 선행 언더스코어(_)
  • 후행 하이픈/대시(-)
  • 두 개의 하이픈/대시

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

이미지 푸시 오류

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

이 문제는 Docker 프로젝트 이슈에서 논의되었으며 레지스트리에서 상대적인 URL을 활성화하는 간단한 해결책일 수 있습니다.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    registry['env'] = {
      "REGISTRY_HTTP_RELATIVEURLS" => true
    }
    
  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 구성하십시오.

Self-compiled (source)
  1. 레지스트리를 배포할 때 생성한 YAML 구성 파일을 편집합니다. 다음 스니펫을 추가합니다:

    http:
        relativeurls: true
    
  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 시작하십시오.

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

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

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

레지스트리 디버그 주소를 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에서 실행되는 것으로 가정합니다:

  1. mitmproxy 설치.
  2. mitmproxy --port 9000를 실행하여 해당 인증서를 생성합니다. 끝내려면 CTRL-C를 누릅니다.
  3. ~/.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 창에 다음과 같은 추적을 볼 수 있습니다:

mitmproxy에서의 Docker 출력

위 이미지는 다음을 보여줍니다:

  • 초기 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

이 경우 다음 단계를 따르세요:

  1. gitlab.rb에서 인스턴스 전체 설정에 대한 컨테이너 레지스트리를 임시로 활성화합니다:

    gitlab_rails['registry_enabled'] = true
    
  2. 변경 사항이 적용되도록 파일을 저장하고 GitLab을 다시 구성합니다.
  3. 제거를 다시 시도하세요.

일반적인 방법으로 리포지터리를 제거할 수 없는 경우 GitLab Rails 콘솔을 사용하여 프로젝트를 강제로 제거할 수 있습니다:

# 제거하려는 프로젝트의 경로
prj = Project.find_by_full_path(<project_path>)

# 위의 코드는 프로젝트의 컨테이너 레지스트리를 삭제하므로 경로를 재확인해주세요!
if prj.has_container_registry_tags?
  prj.container_repositories.each { |p| p.destroy }
end