Docker Hub: toomanyrequests — pull rate limit에 도달함(429)

안녕하세요, BlueByte입니다. 몇 달째 매일 밤 잘 돌던 배포가 새벽 2시에 toomanyrequests: You have reached your pull rate limit로 실패하는데, 코드는 아무것도 바뀐 게 없습니다. 이쪽에서 고장 난 것도 아닙니다. Docker Hub는 이미지 pull을 계정별·출발지 IP별로 세는데, 같은 주소 뒤의 누군가가 공용 예산을 다 써 버린 것입니다. 오늘은 CLI·Kubernetes·BuildKit에서 이 메시지가 어떻게 보이는지, 어떤 한도에 걸렸고 언제 풀리는지 알려 주는 헤더 읽는 법, 원인별 해결(pull이 실제로 일어나는 곳에서 로그인하기, pull-through 캐시, pull 줄이기), 그리고 정말로 더 큰 한도 아래 들어갔는지 확인하는 법까지 하나씩 짚어보겠습니다.

메시지와 그것이 나타나는 자리

Docker Hub는 manifest 요청에 HTTP 429와 아래 본문으로 답하고, 데몬은 레지스트리의 toomanyrequests 코드를 앞에 붙여 그대로 전달합니다:

Error response from daemon: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

Kubernetes에서는 같은 문구가 Pod 이벤트 안에 들어가고, Pod는 ImagePullBackOff를 반복합니다:

Warning  Failed   kubelet  Failed to pull image "nginx:1.27": ... 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit ...

docker build는 FROM 줄에서 failed to resolve source metadata for docker.io/library/...: 429 Too Many Requests로 멈춥니다. 세 군데에서 보이지만 원인은 하나입니다. manifest를 요청한 주체에게 남은 pull이 없었습니다.

예산을 세는 방식, 그리고 사무실 전체가 한꺼번에 막히는 이유

Docker Hub 문서가 숫자를 정합니다. 비인증 pull은 IPv4 주소당(IPv6는 /64당) 100회, 인증한 Personal 계정은 200회이며 둘 다 "6시간 기준으로 계산"됩니다. Pro·Team·Business는 무제한입니다. 중요한 단위는 출발지 주소입니다. NAT 게이트웨이, 사무실 공용 회선, CI 러너 풀은 Docker Hub에 IPv4 주소 하나로 보이므로, 그 뒤의 모든 머신에서 나가는 익명 pull이 같은 100회를 나눠 씁니다. 내 노트북이 로그인돼 있어도 노드의 kubelet이나 파이프라인의 러너에게는 아무 영향이 없습니다. 각자는 자기 신분으로 pull하고, 기본값은 익명입니다.

어떤 한도에 걸렸고 언제 풀리는지 헤더로 읽기

추측하지 말고 레지스트리에 물어보세요. ratelimitpreview/test 이미지가 이 용도로 있고, HEAD 요청은 pull을 소모하지 않고 카운터를 읽습니다:

TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl -sI -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest \
  | grep -iE '^(HTTP|ratelimit|docker-ratelimit)'

HTTP/2 200
docker-ratelimit-source: 203.0.113.10
ratelimit-limit: 100;w=3600
ratelimit-remaining: 100;w=3600

ratelimit-limit이 한도, w=가 초 단위 윈도, ratelimit-remaining이 남은 횟수, docker-ratelimit-source가 지금 세고 있는 주소입니다. 이 주소가 내 머신의 공인 IP가 아니라면 NAT이고, 누군가와 나눠 쓰고 있는 것입니다. 이 확인은 실패한 호스트(노드, 러너)에서 하십시오. 그곳의 주소가 문제이기 때문입니다. 솔직히 덧붙이면, 문서는 w=21600(6시간)을 보여 주지만 제가 클라우드 호스트에서 직접 실행했을 때는 헤더가 w=3600을 돌려줬습니다. 기억하는 숫자보다 자기 헤더의 윈도를 믿으세요. 인증된 시점을 보려면 curl -s --user "$USER:$PAT" ...로 토큰을 받으면 됩니다. ratelimit 헤더가 아예 없다면 유료 플랜이라 한도가 적용되지 않는 경우일 수 있습니다.

해결 1: pull이 실제로 일어나는 곳에서 로그인하기

비밀번호 대신 personal access token을 쓰고, 셸 히스토리에 남지 않게 파이프로 넘기세요:

echo "$DOCKER_PAT" | docker login --username your-user --password-stdin

Login Succeeded

자격 증명은 그 호스트의 그 사용자 $HOME/.docker/config.json에 저장됩니다. CI에서는 토큰을 secret으로 두고 같은 명령을 파이프라인 단계로 넣고, 빌드 서버에서는 빌드를 실제로 돌리는 계정으로 실행하세요. 그런 다음 --user를 붙여 헤더 확인을 다시 하면 한도가 200으로 올라가 있거나, Pro·Team 계정이라면 헤더가 사라져 있어야 합니다.

해결 2: imagePullSecrets로 kubelet에 자격 증명 주기

Kubernetes 노드는 내 노트북의 로그인을 절대 보지 못합니다. Docker Hub 서버 이름으로 레지스트리 secret을 만들어 Pod에서 참조하거나, 네임스페이스의 service account에 붙여 모든 Pod가 물려받게 하세요:

kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=your-user --docker-password="$DOCKER_PAT" \
  --docker-email=you@example.com
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets": [{"name": "regcred"}]}'

spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: web
      image: nginx:1.27
      imagePullPolicy: IfNotPresent

이미 docker login을 했다면 kubectl create secret generic regcred --from-file=.dockerconfigjson=$HOME/.docker/config.json --type=kubernetes.io/dockerconfigjson으로 그 파일을 재사용할 수 있습니다. secret이 생긴 뒤 멈춘 Pod를 지우면 새 Pod가 인증된 상태로 pull합니다.

해결 3: Docker Hub에 같은 질문을 반복하지 않기 — pull-through 캐시

여러 호스트가 같은 이미지를 받는다면 미러가 한 번만 받아 나머지에 로컬로 나눠 줍니다. registry 이미지를 Docker Hub의 프록시로 띄우면 됩니다:

# /etc/docker/registry/config.yml (on the mirror host)
proxy:
  remoteurl: https://registry-1.docker.io
  username: your-user
  password: your-pat

그리고 모든 클라이언트의 /etc/docker/daemon.json이 미러를 가리키게 합니다:

{ "registry-mirrors": ["https://mirror.internal:5000"] }

데몬을 재시작한 뒤 docker info의 Registry Mirrors: 항목에 미러가 나오는지 확인하세요. 문서가 주는 주의 두 가지입니다. 이 방식으로 미러링할 수 있는 건 Docker Hub뿐이고, 미러에 자격 증명을 넣으면 그 계정이 볼 수 있는 모든 비공개 이미지가 미러에 접근하는 누구에게나 읽히므로 앞단에 인증을 세워야 합니다. containerd 노드에서는 같은 설정이 containerd의 registry host 설정에 있습니다.

실제 사례: NAT 게이트웨이 한도에 걸린 새벽 2시 롤아웃

12노드 클러스터가 매일 밤 새 릴리스를 롤아웃했습니다. 어느 날 밤 모든 Pod가 ImagePullBackOff에 멈췄고 kubectl describe pod에 위의 429가 찍혔습니다. 노드에서 헤더를 확인하니 ratelimit-remaining: 0이었고, docker-ratelimit-source는 VPC의 NAT 게이트웨이 주소였습니다. 같은 서브넷의 kubelet 12개와 CI 러너 하나가 주소 하나의 100회를 익명으로 나눠 쓰고 있었던 것입니다. 각 네임스페이스의 default service account에 regcred를 붙이고 워크로드에 imagePullPolicy: IfNotPresent를 준 것이 해결이었고, 미러는 일주일 뒤에 들어갔습니다. 같은 노드에서 다시 확인하니 ratelimit-limit: 200이 나왔고 롤아웃은 깨끗하게 이미지를 받았습니다.

확인하고, 카운터가 다시 차오르지 않게 하기

어떤 해결이든 노트북이 아니라 실패했던 호스트에서 증명하세요:

TOKEN=$(curl -s --user "$DOCKER_USER:$DOCKER_PAT" "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl -sI -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest | grep -i ratelimit

한도가 200이면 Personal 로그인이 쓰이고 있는 것이고, 헤더가 없으면 유료 플랜입니다. 한도 아래에 머물려면 latest 대신 태그를 고정하고 imagePullPolicy: IfNotPresent로 재시작 때 노드 캐시를 재사용하게 하고, 모든 파이프라인에 빌드 단계로 로그인을 넣고, 클러스터와 러너 풀 앞에 미러를 두고, 노드에서 ratelimit-remaining을 주기적으로 지켜봐서 롤아웃이 먼저 알아채기 전에 예산이 줄어드는 걸 보십시오.

ImagePullBackOff·abuse 한도와 어떻게 다른지

ImagePullBackOff는 원인이 아니라 상태입니다. 잘못된 태그, 비공개 저장소의 pull secret 누락, 그리고 이 rate limit이 모두 거기서 끝나며, 이벤트 문구만이 셋을 가릅니다. manifest unknown, unauthorized, toomanyrequests입니다. Docker Hub에는 별도의 abuse rate limit도 있어서 웹 페이지와 API를 포함한 모든 요청에 pull 한도 본문 없이 429 Too Many Requests로 답합니다. 이쪽은 한 주소에서 요청이 몰릴 때 발생하며, 답은 로그인이 아니라 속도를 늦추는 것입니다. 다음에 pull이 429로 죽으면 실패한 호스트에서 먼저 헤더를 확인해 보세요. 주소·한도·시계를 한 줄로 알려 줍니다.