2025년 4월 1일부터 Docker는 Docker Hub에 새로운 pull rate limit을 적용할 예정이며, 이는 GitLab에서 실행되는 파이프라인을 포함해 업계 전반의 CI/CD 파이프라인에 중대한 영향을 미칠 수 있습니다. 가장 큰 변화는 인증되지 않은 사용자에게 6시간당 100회 pull limit이 적용된다는 점입니다.

무엇이 변경되나요?​

4월 1일부터 Docker는 다음과 같은 pull rate limit을 적용합니다.

2025-04-04-dockerhub-rate-limit-0 | 인포그랩 GitLab

이 내용이 특히 중요한 이유는 다음과 같습니다.

  • GitLab의 의존성 프록시(Dependency Proxy)는 현재 Docker Hub에서 인증되지 않은 사용자로 pull을 수행합니다.
  • 의존성 프록시를 사용하지 않는 대부분의 CI/CD 파이프라인은 Docker Hub에서 인증되지 않은 사용자로 직접 pull을 수행합니다.
  • GitLab.com의 호스팅 러너(hosted runner)에서는 여러 사용자가 동일한 IP 주소 또는 서브넷을 공유할 수 있으므로, 해당 제한이 공동으로 적용될 수 있습니다.

GitLab 사용자에게 미치는 영향​

Docker Hub에서 직접 Pull 할 때 영향​

CI/CD 파이프라인이 Docker Hub에서 인증 없이 이미지를 직접 pull 할 때, 이는 IP 주소당 6시간에 100회로 제한됩니다. 파이프라인을 자주 실행하거나 동일한 러너 인프라를 공유하는 여러 프로젝트에서 파이프라인을 실행할 때, 이 제한은 빠르게 소진돼 파이프라인 실패로 이어질 수 있습니다.

GitLab 의존성 프록시(Dependency Proxy)에 미치는 영향​

GitLab의 의존성 프록시(Dependency Proxy) 기능은 Docker 이미지를 GitLab 내에 캐시해 파이프라인 속도를 높이고 외부 의존성을 줄일 수 있습니다. 그러나 현재 구현은 Docker Hub에서 인증되지 않은 사용자로 pull을 수행하므로, 6시간당 100회 제한이 적용됩니다.

호스팅 러너에 미치는 영향​

GitLab.com의 호스팅 러너(hosted runner)에서는 Google Cloud의 pull-through 캐시를 사용합니다. 이는 자주 pull 하는 이미지를 미러링해 rate limit을 피하도록 돕습니다. .gitlab-ci.yml 파일의 image: 또는 services:에 정의된 Job 이미지는 rate limit의 영향을 받지 않습니다.

그러나 러너 환경 내에서 이미지를 pull 할 때마다 상황은 조금 더 복잡해집니다. 러너 런타임 동안 이미지를 pull 하는 가장 일반적인 사용 사례는 Docker-in-Docker 또는 Kaniko를 사용해 이미지를 빌드할 때입니다. 이때 Dockerfile에 정의된 Docker Hub 이미지가 Docker Hub에서 직접 pull 되므로, rate limit의 영향을 받을 수 있습니다.

GitLab의 대응 방안​

GitLab은 이러한 문제를 완화하기 위해 여러 솔루션을 적극적으로 마련하고 있습니다.

  • 의존성 프록시 인증: GitLab의 의존성 프록시(Dependency Proxy) 기능에 Docker Hub 인증 지원을 추가했습니다. 이는 의존성 프록시가 인증된 사용자로 Docker Hub에서 이미지를 pull 하도록 해 rate limit을 크게 완화합니다.
  • 문서 업데이트: Docker Hub의 파이프라인 인증 구성에 명확한 지침을 제공하기 위해 문서를 업데이트했습니다.
  • 내부 인프라 준비: GitLab.com의 호스팅 러너(hosted runner)에 미치는 영향을 최소화하기 위해 내부 인프라를 준비하고 있습니다.

사용자가 준비할 조치​

옵션 1: 파이프라인에 Docker Hub 인증 구성하기​

Docker Hub에서 직접 pull 하는 파이프라인에서는 인증을 구성하면 rate limit을 6시간당 200회로 늘릴 수 있습니다(또는 Docker Hub 유료 구독 시 무제한).

Docker Hub 자격 증명을 프로젝트 또는 그룹 CI/CD 변수에 추가하세요(.gitlab-ci.yml 파일이 아닌). DOCKER_AUTH_CONFIG CI/CD 변수를 올바르게 설정하는 방법은 GitLab의 Docker 이미지 사용 가이드를 참조하세요.

옵션 2: GitLab 컨테이너 레지스트리(Container Registry) 사용하기​

자주 사용하는 Docker 이미지를 GitLab 컨테이너 레지스트리(Container Registry)에 push 하는 것도 고려하세요. 이렇게 하면 CI/CD 실행 시 Docker Hub에서 pull 할 필요가 없습니다.

  1. Docker Hub에서 이미지를 pull
  2. GitLab 컨테이너 레지스트리용으로 태그 지정
  3. GitLab 컨테이너 레지스트리에 push
  4. GitLab 컨테이너 레지스트리에서 pull 하도록 파이프라인 업데이트
docker pull busybox:latest
docker tag busybox:latest $CI_REGISTRY_IMAGE/busybox:latest
docker push $CI_REGISTRY_IMAGE/busybox:latest

.gitlab-ci.yml 파일 예시:

image: $CI_REGISTRY_IMAGE/busybox:latest

옵션 3: GitLab 의존성 프록시(Dependency Proxy) 사용하기​

GitLab 의존성 프록시(Dependency Proxy) 기능은 Docker 이미지를 캐시하고 프록시 처리해 외부 의존성과 rate limit 문제를 줄이는 방법을 제공합니다.

현재 인증 옵션:

  • GitLab 17.10: GraphQL API를 사용해 의존성 프록시의 Docker Hub 인증 구성
  • GitLab 17.11: 그룹 설정에서 새로운 UI 기반 구성 사용(GitLab.com에서 이미 사용 가능)

인증이 올바르게 구성되면, 다음 작업을 수행합니다.

  1. 그룹의 의존성 프록시 설정에서 Docker Hub 자격 증명 구성
    • GitLab 17.11 이상(또는 GitLab.com): 그룹 설정 > Packages & Registries > Dependency Proxy로 이동
    • GitLab 17.10: GraphQL API를 사용해 인증 구성
  2. 파이프라인을 업데이트해 CI/CD 구성에 Dependency Proxy URL 사용: image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/busybox:latest

옵션 4: Docker Hub 유료 구독 고려하기​

Docker Hub을 대량으로 사용하는 조직에서는 Team 또는 Business로 Docker 유료 구독을 업그레이드하면 무제한 pull을 제공받으므로, 가장 간단한 해결책이 될 수 있습니다.

Docker Hub rate limit 영향을 줄이는 모범 관행​

어떤 옵션을 선택하든, Docker Hub의 rate limit 영향을 최소화하려면 다음 모범 관행을 고려하세요.

  • latest 대신 특정 이미지 태그를 사용하여 불필요한 pull을 방지하세요.
  • 여러 프로젝트에서 동일한 베이스 이미지를 사용하도록 Dockerfile을 통합하세요.
  • 덜 중요한 파이프라인은 비혼잡 시간대에 실행되도록 예약하세요.
  • 캐싱을 효과적으로 사용해 동일한 이미지를 반복해서 pull 하지 않도록 하세요.

참고: Docker Hub 문서에 따르면, pull 횟수는 이미지 크기나 레이어 수가 아니라, 이미지 매니페스트를 pull 할 때 증가합니다.

일정과 향후 조치​

지금​

  • Docker Hub에서 직접 pull 할 때, 인증을 구현하세요.
  • GitLab.com 사용자는 다음 두 가지 방법의 하나로 의존성 프록시(Dependency Proxy)에 Docker Hub 인증을 구성할 수 있습니다.
    • GraphQL API
    • 그룹 설정의 UI
  • Self-managed GitLab 17.10 사용자는 GraphQL API를 사용해 의존성 프록시 인증을 구성할 수 있습니다.

2025년 4월 1일​

  • Docker Hub rate limit이 적용됩니다.

2025년 4월 17일​

  • GitLab 17.11 릴리즈에는 Self-managed 인스턴스를 위한 UI 기반 의존성 프록시 인증 지원이 포함됩니다.

예상치 못한 파이프라인 실패를 방지하려면 4월 1일 마감일 이전에 조치를 취하는 걸 권장합니다. 대부분의 사용자에게는 Docker Hub 인증으로 의존성 프록시를 구성하는 게 장기적으로 가장 효율적인 해결책입니다.

(이 포스트는 GitLab의 동의를 받아 공식 블로그의 영문 포스트를 우리말로 번역한 글입니다.)

위 조치에 궁금한 점이 있거나 도움이 필요하신가요? DevOps 전문 기업 인포그랩에 문의하세요!