Dependency Proxy

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated
  • 이동됨. GitLab 13.6에서 GitLab 프리미엄에서 GitLab 무료로
  • 소개됨. GitLab 13.7에서 GitLab 내의 개인 그룹 지원 추가
  • 공개 그룹에서 이미지에 대한 익명 액세스는 더 이상 GitLab 13.7에서 사용할 수 없습니다.
  • 소개됨. GitLab 13.10에서 pull-by-digest 및 Docker 20.x 버전 지원 추가

GitLab Dependency Proxy는 자주 액세스하는 상위 이미지에 대해 사용할 수 있는 로컬 프록시입니다.

CI/CD의 경우, Dependency Proxy는 요청을 받아 레지스트리에서 상위 이미지를 반환하여 pull-through 캐시로 작동합니다.

전제 조건

Dependency Proxy를 사용하려면 GitLab 인스턴스에서 활성화해야 합니다. 기본적으로 활성화되어 있지만 관리자가 꺼도록 설정할 수 있습니다.

지원되는 이미지 및 패키지

다음 이미지와 패키지가 지원됩니다.

이미지/패키지 GitLab 버전
Docker 11.11+

계획된 추가 기능 목록은 방향 페이지에서 확인하세요.

그룹을 위한 Dependency Proxy 활성화 또는 비활성화

그룹을 위해 Dependency Proxy를 활성화 또는 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 패키지 및 레지스트리를 선택합니다.
  3. Dependency Proxy 섹션을 확장합니다.
  4. 프록시를 활성화하려면 프록시 사용를 켭니다. 비활성화하려면 토글을 끄세요.

이 설정은 그룹을 위한 Dependency Proxy에만 영향을 미칩니다. 전체 GitLab 인스턴스의 Dependency Proxy를 켜거나 끄는 것은 관리자만 할 수 있습니다.

Dependency Proxy 보기

Dependency Proxy를 보려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 운영 > Dependency Proxy를 선택합니다.

Dependency Proxy는 프로젝트에서 사용할 수 없습니다.

Docker 이미지에 대한 Dependency Proxy 사용

GitLab을 Docker 이미지의 소스로 사용할 수 있습니다.

전제 조건:

  • 이미지는 Docker Hub에 저장되어 있어야 합니다.

Dependency Proxy로 인증

  • 소개됨. GitLab 13.7에서 dependency_proxy_for_private_groups란 이름의 플래그로 추가됨. 기본적으로 활성화됨.
  • GitLab 15.0에서 dependency_proxy_for_private_groups 기능 플래그가 제거되었습니다.
  • 그룹 액세스 토큰 지원이 GitLab 16.3에서 추가됨.

Dependency Proxy는 그룹과 관련된 공간에 Docker 이미지를 저장하므로 Dependency Proxy에 대해 인증해야 합니다.

개인 레지스트리에서 이미지 사용 지침을 따르되, registry.example.com:5000 대신 포트 없이 GitLab 도메인 gitlab.example.com을 사용합니다.

예를 들어, 수동으로 로그인: 

docker login gitlab.example.com --username my_username --password my_password

다음을 사용하여 인증할 수 있습니다:

개인 액세스 토큰 또는 사용자 이름과 암호로 Dependency Proxy에 액세스하는 사용자는 이미지를 가져오는 그룹에 대해 최소한 손님 역할을 가져야 합니다.

Dependency Proxy는 Docker v2 토큰 인증 흐름을 따라 client에게 pull 요청에 사용할 JWT를 제공합니다. 인증된 JWT는 일정 시간 후에 만료됩니다. 토큰이 만료되면 대부분의 Docker 클라이언트는 자격 증명을 저장하고 추가 조치없이 새 토큰을 요청합니다.

토큰 만료 시간은 구성 가능한 설정입니다. GitLab.com에서는 만료 시간이 15분입니다.

SAML SSO

SAML SSO이 활성화되면 사용자는 종속성 프록시를 통해 이미지를 가져오기 전에 SSO를 통해 로그인해야 합니다.

CI/CD 내에서 인증

  • GitLab 13.7에서 도입됨.
  • 작업에 이미지를 가져오기 위해 종속성 프록시를 사용할 때 자동 실행자 인증은 GitLab 13.9에 추가되었습니다.
  • 대문자를 포함하는 그룹 이름의 접두어가 GitLab 13.10에서 수정되었습니다.

실행자는 종속성 프록시에 자동으로 로그인합니다. 종속성 프록시를 통해 가져오려면 사전 정의된 변수 중 하나를 사용하십시오:

  • CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX는 최상위 그룹을 통해 가져옵니다.
  • CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX는 서브그룹이나 직접 프로젝트가 있는 그룹을 통해 가져옵니다.

최신 alpine 이미지를 가져오는 예시: 

# .gitlab-ci.yml
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine:latest

또한 사용할 수 있는 기타 사전 정의된 CI/CD 변수들이 있습니다:

  • CI_DEPENDENCY_PROXY_USER: 종속성 프록시에 로그인하는 CI/CD 사용자입니다.
  • CI_DEPENDENCY_PROXY_PASSWORD: 종속성 프록시에 로그인하는 CI/CD 비밀번호입니다.
  • CI_DEPENDENCY_PROXY_SERVER: 종속성 프록시에 로그인하는 서버입니다.
  • CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX: 최상위 그룹을 통해 종속성 프록시를 통해 이미지를 가져오기 위한 이미지 접두사입니다.
  • CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX: 프로젝트가 속한 직접 그룹이나 서브그룹을 통해 종속성 프록시를 통해 이미지를 가져오기 위한 이미지 접두사입니다.

CI_DEPENDENCY_PROXY_SERVER, CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX, 그리고 CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX는 서버 포트를 포함합니다. 종속성 프록시 경로를 명시적으로 포함하는 경우, 수동으로 포트를 포함하지 않고 종속성 프록시에 로그인한 경우를 제외하고 포트를 포함해야 합니다: 

docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest

이미지를 빌드할 때 종속성 프록시를 사용하는 예시: 

# Dockerfile
FROM gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest

# .gitlab-ci.yml
image: docker:20.10.16

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""

services:
  - docker:20.10.16-dind

build:
  image: docker:20.10.16
  before_script:
    - docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER
  script:
    - docker build -t test .

또한 개인 액세스 토큰 또는 배포 토큰을 저장하고 액세스하는 데 사용할 사용자 정의 CI/CD 변수를 사용할 수도 있습니다.

종속성 프록시 캐시에 Docker 이미지 저장

종속성 프록시 저장소에 Docker 이미지를 저장하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 운영 > Dependency Proxy를 선택합니다.
  3. Dependency Proxy 이미지 접두사를 복사합니다.
  4. 다음 중 하나의 명령을 사용합니다. 이러한 예시에서 이미지는 alpine:latest입니다.

  5. 정확히 원하는 이미지의 버전을 지정하려면 해시값으로 이미지를 가져올 수도 있습니다.

    • 이미지를 가져오려면 이미지를 .gitlab-ci.yml 파일에 추가합니다: 

      image: gitlab.example.com/groupname/dependency_proxy/containers/alpine:latest

    • 이미지를 가져오려면 디제스트를 사용하여 이미지를 .gitlab-ci.yml 파일에 추가합니다: 

      image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc

    • Docker 이미지를 수동으로 가져옵니다: 

      docker pull gitlab.example.com/groupname/dependency_proxy/containers/alpine:latest

    • Dockerfile에 URL을 추가합니다: 

      FROM gitlab.example.com/groupname/dependency_proxy/containers/alpine:latest

GitLab은 Docker Hub에서 Docker 이미지를 가져와 GitLab 서버에서 blobs를 캐시합니다. 동일한 이미지를 다시 가져오는 경우 GitLab은 Docker Hub에서 이미지의 최신 정보를 가져오지만 기존 blobs를 GitLab 서버에서 제공합니다.

스토리지 사용량 줄이기

의존성 프록시의 스토리지 사용량을 줄이는 방법에 대한 정보는 의존성 프록시 스토리지 사용량 줄이기를 참조하세요.

Docker Hub 속도 제한 및 의존성 프록시

의존성 프록시를 사용하여 Docker Hub 속도 제한을 피하는 방법은 여기서 확인하세요.

2020년 11월, Docker는 Docker Hub의 풀 요청에 대한 속도 제한을 도입했습니다. 귀하의 GitLab CI/CD 구성이 Docker Hub에서 이미지를 사용하는 경우 각 작업을 실행할 때마다 풀 요청으로 계산될 수 있습니다. 이 제한을 우회하는 데 도움을 주기 위해 의존성 프록시 캐시에서 이미지를 가져올 수 있습니다.

이미지를 가져오면(예: docker pull 명령 또는 .gitlab-ci.yml 파일에서 image: foo:latest) Docker 클라이언트는 요청의 모음을 만듭니다:

  1. 이미지 매니페스트가 요청됩니다. 매니페스트에는 이미지를 빌드하는 방법에 대한 정보가 포함되어 있습니다.
  2. 매니페스트를 사용하여 Docker 클라이언트는 한 번에 하나씩 blob라고도 하는 레이어의 모음을 요청합니다.

Docker Hub 속도 제한은 매니페스트 요청을 기반으로 합니다. 의존성 프록시는 주어진 이미지의 매니페스트와 blob을 모두 캐시하므로 다시 요청할 때 Docker Hub에 연락할 필요가 없습니다.

GitLab은 캐시된 태그 이미지가 오래된지 어떻게 알까요?

alpine:latest와 같은 이미지 태그를 사용하는 경우 이미지는 시간이 지남에 따라 변경됩니다. 각 변경 시에 매니페스트에는 요청할 blob에 대한 다른 정보가 포함됩니다. 의존성 프록시는 매니페스트가 변경될 때만 새 이미지를 가져오지며 매니페스트가 오래된지 여부만 확인합니다.

Docker는 이미지 매니페스트에 대한 HEAD 요청을 속도 제한에 포함하지 않습니다. alpine:latest에 대한 HEAD 요청을 할 수 있고 헤더에서 반환된 다이제스트(체크섬) 값을 볼 수 있으며 매니페스트가 변경되었는지 결정할 수 있습니다.

의존성 프록시는 모든 요청을 HEAD 요청으로 시작합니다. 매니페스트가 오래된 경우에만 새 이미지가 가져와집니다.

예를 들어 파이프라인이 5분마다 node:latest를 가져오면 의존성 프록시는 전체 이미지를 캐시하고, node:latest가 변경되는 경우에만 업데이트합니다. 따라서 6시간 동안 이미지에 대해 360개의 요청(도커 허브 속도 제한을 초과함)이 아니라 매니페스트가 그 기간 동안 변경된 경우에만 하나의 풀 요청이 발생합니다.

Docker Hub 속도 제한 확인

Docker Hub로의 요청 횟수와 남은 횟수에 대해 궁금하다면, 이러한 명령을 실행하여 러너에서 또는 심지어 CI/CD 스크립트에서 실행할 수 있습니다: 

# 참고: 이 명령을 실행하려면 jq을 설치해야 합니다.
TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 | grep --ignore-case RateLimit
...

출력 예시: 

RateLimit-Limit: 100;w=21600
RateLimit-Remaining: 98;w=21600

이 예시는 6시간 동안 총 100회의 풀 가능 한도와 남은 98회를 보여줍니다.

CI/CD 작업에서 속도 제한 확인

이 예시에서는 jq와 curl이 설치된 GitLab CI/CD 작업을 보여줍니다: 

hub_docker_quota_check:
    stage: build
    image: alpine:latest
    tags:
        - <optional_runner_tag>
    before_script: apk add curl jq
    script:
      - |
        TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1

문제 해결

인증 오류: “HTTP Basic: 액세스 거부됨”

의존성 프록시에 대한 인증 중 “HTTP Basic: 액세스 거부됨” 오류가 발생하는 경우, 이중 인증 문제 해결 가이드를 참조하세요.

의존성 프록시 연결 실패

서비스 별칭이 설정되지 않으면 docker:20.10.16 이미지에서 dind 서비스를 찾을 수 없어 다음과 유사한 오류가 발생합니다: 

error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host

이는 Docker 서비스를 위해 서비스 별칭을 설정함으로써 해결할 수 있습니다: 

services:
    - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind
      alias: docker

CI/CD 작업에서 의존성 프록시에 대한 인증 문제

GitLab Runner는 의존성 프록시에 자동으로 인증됩니다. 그러나 기본 Docker 엔진은 여전히 인가 해결 프로세스에 따라 동작합니다.

인증 메커니즘의 오 Misconfigurations는 HTTP 기본: 액세스 거부 및 403 : 액세스 금지 오류를 일으킬 수 있습니다.

Job 로그를 사용하여 의존성 프록시에 대한 인증 메커니즘을 확인할 수 있습니다: 

$DOCKER_AUTH_CONFIG의 자격 증명으로 인증 중

/root/.docker/config.json에서 자격 증명으로 인증 중

작업 페이로드(GitLab 레지스트리)에서 자격 증명으로 인증 중

예상된 인증 메커니즘을 사용하는지 확인하십시오.

이미지를 가져올 때 Not Found 또는 404 오류

이러한 오류는 해당 사용자가 의존성 프록시 그룹에서 최소한의 “게스트” 역할을 가지고 있지 않을 수 있음을 나타낼 수 있습니다: 

  • 오류: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: 찾을 수 없음

frontend dockerfile.v0으로 해결하지 못했습니다: LLB 정의를 만들지 못했습니다: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: 찾을 수 없음

  • 오류: 작업 실패: 지정된 정책 [항상]으로 이미지 "gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest"을 가져오지 못했습니다:
데몬으로부터 오류 응답: HTTP 404 응답 바디 구문 분석 오류: 예상치 못한 JSON 입력 끝: "" (manager.go:237:1초)

Access denied와 유사한 경우의 오류 메시지를 개선하는 작업에 대한 자세한 내용은 이슈 354826를 참조하십시오.

의존성 프록시에서 이미지를 실행할 때 exec format error

참고: 이 문제는 GitLab 16.3에서 해결되었습니다. 16.2 또는 이전 버전을 사용하는 자체 관리 인스턴스의 경우 인스턴스를 16.3으로 업데이트하거나 아래에 문서화된 해결책을 사용할 수 있습니다.

이 오류는 GitLab 16.2 이전의 ARM 기반 Docker 설치에서 의존성 프록시를 사용하려고 시도하는 경우 발생합니다. 의존성 프록시는 특정 태그가있는 이미지를 가져올 때 x86_64 아키텍처만 지원합니다.

해결책으로 의존성 프록시에 다른 아키텍처의 이미지를 끌어당기도록 SHA256를 명시할 수 있습니다: 

docker pull ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/library/docker:20.10.3@sha256:bc9dcf5c8e5908845acc6d34ab8824bca496d6d47d1b08af3baf4b3adb1bd8fe

이 예에서 bc9dcf5c8e5908845acc6d34ab8824bca496d6d47d1b08af3baf4b3adb1bd8fe는 ARM 기반 이미지의 SHA256입니다.