Docker Hub Rate Limiting 정책과 "authorization failed" 오류 이해하기

컨테이너 이미지를 다루다 보면, docker pull 과정에서 "authorization failed" 또는 429 Too Many Requests 오류를 경험할 수 있습니다. 이는 대체로 Docker Hub의 rate limiting 정책 때문입니다. 이번 글에서는 Docker Hub 공식 문서에 기반하여, 이 정책이 무엇이고 어떤 영향을 주며 어떻게 대응할 수 있는지 정리해 보겠습니다.

---

1. Docker Hub Rate Limiting이란?

Docker Hub는 2020년 11월부터 이미지 pull 요청 횟수에 제한(rate limit) 을 두었습니다. 이는 과도한 트래픽으로 인한 서비스 안정성 저하를 방지하고, 유료 플랜 사용자에게 더 나은 품질을 제공하기 위함입니다.

공식 문서에 따르면, 6시간 단위로 pull 요청 횟수가 제한됩니다.

---

2. 사용자 유형별 Pull 제한

사용자 유형 기준 제한(6시간)

익명 사용자 (로그인 X)	IP 주소 기준	100회
무료 계정 로그인 사용자	Docker ID 기준	200회
Pro / Team (유료)	계정 기준	무제한

즉, 로그인을 하지 않고 pull 하면 IP 단위로 100회까지만 허용되며, 로그인하면 200회까지 늘어납니다. Pro 또는 Team 플랜을 사용하면 제한이 없어집니다.

📌 참고: Docker Hub Usage & Limits 공식 문서

---

3. Rate Limit 초과 시 발생하는 오류

제한을 초과하면 다음과 같은 오류가 발생합니다:

• 429 Too Many Requests
• authorization failed

이때 API 응답 헤더에는 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset 값이 포함되어, 현재 제한 상태를 확인할 수 있습니다.

RateLimit-Limit: 200;w=21600
RateLimit-Remaining: 0;w=21600
RateLimit-Reset: 1373

• RateLimit-Limit : 6시간 동안 허용되는 최대 pull 횟수
• RateLimit-Remaining : 남은 pull 가능 횟수
• RateLimit-Reset : 제한이 초기화되기까지 남은 시간(초)

---

4. Rate Limit이 문제되는 상황

1. CI/CD 환경에서 반복 빌드
   • 매번 docker pull 실행 → 빠르게 횟수 초과
2. 쿠버네티스 노드가 많을 때
   • 같은 이미지를 여러 노드에서 동시에 pull
3. 로그인 없이 사용
   • 익명 사용자로 인식 → 100회 제한 적용

---

5. 해결 방법 (공식 문서 권장)

Docker 공식 문서에서는 다음과 같은 방법들을 권장합니다:

(1) 로그인 사용

익명 사용자보다는 로그인 사용자가 pull 제한이 더 큽니다.

docker login -u <username> -p <password>

(2) 내부 레지스트리 사용

이미지를 매번 Docker Hub에서 가져오지 말고, 자체 레지스트리(예: AWS ECR, GCP Artifact Registry, Harbor 등)에 미러링하여 사용하면 안정적입니다.

(3) 유료 플랜 사용

팀 규모가 크거나 CI/CD 파이프라인에서 pull 요청이 많다면, Pro/Team 플랜을 사용하는 것이 현실적입니다.

---

6. 결론

Docker Hub의 rate limiting 정책은 서비스 안정성을 위한 필수 장치입니다. 하지만 실제 운영 환경에서는 CI/CD와 쿠버네티스 환경에서 빈번히 제한에 걸릴 수 있습니다. 따라서 로그인 활용, 내부 레지스트리 운영, 혹은 유료 플랜 사용이 가장 현실적인 해결책입니다.