지금 준비하세요! Docker Hub Rate Limit이 GitLab CI/CD에 영향을 미칩니다

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

무엇이 변경되나요?

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

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

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 할 필요가 없습니다.

Docker Hub에서 이미지를 pull
GitLab 컨테이너 레지스트리용으로 태그 지정
GitLab 컨테이너 레지스트리에 push
GitLab 컨테이너 레지스트리에서 pull 하도록 파이프라인 업데이트

bash

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에서 이미 사용 가능)

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

그룹의 의존성 프록시 설정에서 Docker Hub 자격 증명 구성
- GitLab 17.11 이상(또는 GitLab.com): 그룹 설정 > Packages & Registries > Dependency Proxy로 이동
- GitLab 17.10: GraphQL API를 사용해 인증 구성
파이프라인을 업데이트해 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 전문 기업 인포그랩에 문의하세요!