Docker Hub 풀 사용량과 제한

Docker Hub 풀 사용량과 제한 (Docker Hub pull usage and limits)

Docker Hub의 풀 정의, 풀 귀속(attribution), 인증 방법, 월간 풀 확인, 그리고 풀 rate limit 확인 방법을 배워볼게요.

출처: 문서

본문

비인증 사용자와 Docker Personal 사용자는 Docker Hub에서 6시간 풀 rate limit이 적용돼요. 반면 Docker Pro, Team, Business 사용자는 무제한 풀 rate의 혜택을 받아요. 다음 풀 사용량과 제한은 공정 사용에 따라 구독에 적용돼요:

사용자 유형 6시간당 풀 rate limit
Business (인증) 무제한
Team (인증) 무제한
Pro (인증) 무제한
Personal (인증) 200
비인증 사용자 IPv4 주소 또는 IPv6 /64 서브넷당 100

풀 정의 (Pull definition)

풀은 다음과 같이 정의돼요:

  • Docker 풀은 버전 확인(version check)과 풀의 결과로 발생하는 다운로드를 모두 포함해요. 클라이언트에 따라 docker pull은 버전 확인을 수행해 이미지나 태그를 다운로드하지 않고 존재를 검증할 수 있어요.
  • 버전 확인은 사용량 요금에 포함되지 않아요.
  • 일반 이미지의 풀은 단일 매니페스트(manifest)에 대해 한 번의 풀을 만든다. 멀티 아키텍처 이미지의 풀은 서로 다른 아키텍처 각각에 대해 한 번의 풀로 계산돼요.

풀 귀속 (Pull attribution)

인증 사용자의 풀은 개인 또는 조직 네임스페이스 중 하나에 귀속될 수 있어요. 귀속은 다음에 기반해요:

  • 비공개 풀: 비공개 저장소의 풀은 저장소의 네임스페이스 소유자에게 귀속돼요.
  • 공개 풀: 공개 저장소에서 이미지를 풀할 때 귀속은 도메인 소속과 조직 구성에 따라 결정돼요.
  • 검증된 도메인 소유: 검증된 도메인에 연결된 계정에서 이미지를 풀할 때 귀속은 해당 도메인의 소유자 로 설정돼요.
  • 단일 조직 구성:
    • 검증된 도메인의 소유자가 회사이고 사용자가 그 회사 내 단 하나의 조직에만 속해 있다면, 풀은 그 특정 조직에 귀속돼요.
    • 사용자가 단 하나의 조직에만 속해 있다면 풀은 그 특정 조직에 귀속돼요.
  • 여러 조직 구성: 사용자가 회사 아래 여러 조직에 속해 있다면 풀은 사용자의 개인 네임스페이스에 귀속돼요.

인증 (Authentication)

풀의 올바른 귀속을 보장하려면 Docker Hub로 인증해야 해요. 다음 섹션은 풀을 인증하기 위해 Docker Hub에 로그인하는 방법에 대한 정보를 제공해요.

Docker Desktop

Docker Desktop을 사용 중이라면 Docker Desktop 메뉴에서 Docker Hub에 로그인할 수 있어요. Docker Desktop 메뉴에서 Sign in / Create Docker ID 를 선택하고 화면의 지침에 따라 로그인 과정을 완료해요.

Docker Engine

독립형 Docker Engine을 사용 중이라면 터미널에서 docker login 명령을 실행해 Docker Hub에 인증해요. 명령 사용 방법은 docker login 문서를 참고해요.

Docker Swarm

Docker Swarm을 실행 중이라면 --with-registry-auth 플래그를 사용해 Docker Hub에 인증해야 해요. 자세한 내용은 Create a service 문서를 참고해요. Docker Compose 파일로 애플리케이션 스택을 배포한다면 docker stack deploy 문서를 참고해요.

GitHub Actions

GitHub Actions로 Docker 이미지를 빌드·푸시해 Docker Hub에 올린다면 login action 을 참고해요. 다른 Action을 사용한다면 인증을 위해 비슷한 방식으로 사용자 이름과 액세스 토큰을 추가해야 해요.

Kubernetes

Kubernetes를 실행 중이라면 인증에 대한 정보는 Pull an Image from a Private Registry 의 지침을 따라요.

타사 플랫폼

타사 플랫폼을 사용한다면 레지스트리 인증 사용에 대한 제공자의 지침을 따라요.

참고: 타사 플랫폼을 통해 이미지를 풀할 때 플랫폼이 여러 사용자에 대해 같은 IPv4 주소 또는 IPv6 /64 서브넷을 사용해 이미지를 풀할 수 있어요. 인증된 상태라도 단일 IPv4 주소 또는 IPv6 /64 서브넷에 귀속된 풀은 abuse rate limiting 을 유발할 수 있어요.

Artifactory, AWS CodeBuild, AWS ECS/Fargate, Azure Pipelines, Chipper CI, CircleCI, Codefresh, Drone.io, GitLab, LayerCI, TeamCity에 대한 각 문서 링크는 원문에서 확인해요.

월간 풀 및 포함 사용량 보기

Docker Hub의 Usage 페이지에서 월간 풀을 볼 수 있어요. 그 페이지에서 다음 상세 정보를 포함하는 CSV 파일을 이메일로 보낼 수도 있어요.

CSV 열 정의 사용 지침
datehour 데이터 전송을 초래한 풀의 날짜와 시간 ( yyyy/mm/dd/hh ) 피크 사용 시간과 패턴 식별에 도움
user_name 이미지를 풀한 사용자의 Docker ID 조직 소유자가 사용자별 데이터 소비를 추적하고 리소스를 효과적으로 관리하게 함
repository 풀된 이미지의 저장소 이름 가장 자주 접근되고 데이터 전송을 가장 많이 소비하는 저장소 식별에 도움
access_token_name Docker CLI 인증에 사용된 액세스 토큰 이름. generated 토큰은 사용자가 로그인할 때 Docker 클라이언트가 자동 생성 개인 액세스 토큰은 보통 자동화 도구(Docker Desktop, CI/CD 도구 등)를 인증하는 데 사용. 어떤 자동화 시스템이 풀을 발행했는지 식별에 유용
ips 이미지를 풀하는 데 사용된 IP 주소. 이 필드는 집계되어 같은 날짜·시간에 이미지를 풀한 모든 IP를 나타내는 여러 IP 주소가 나타날 수 있음 데이터 전송의 출처를 이해하고 자동·수동 풀의 패턴 진단·식별에 유용
repository_privacy 풀된 이미지 저장소의 개인 정보 상태. public 또는 private일 수 있음 공개·비공개 저장소를 구분해 풀이 어느 데이터 전송 임계값에 영향을 주는지 식별
tag 이미지의 태그. 풀에 태그가 포함된 경우에만 사용 가능 이미지 식별에 도움. 태그는 종종 특정 버전이나 변형을 식별하는 데 사용
digest 이미지의 고유 digest 이미지 식별에 도움
version_checks 각 이미지 저장소의 날짜·시간에 대해 누적된 버전 확인 수. 클라이언트에 따라 풀은 다운로드 없이 이미지·태그 존재를 확인하는 버전 확인을 할 수 있음 버전 확인 빈도 식별에 도움. 사용 추세와 예상치 못한 동작 분석에 사용 가능
pulls 각 이미지 저장소의 날짜·시간에 대해 누적된 풀 수 저장소 풀 빈도 식별에 도움. 사용 추세와 예상치 못한 동작 분석에 사용 가능

풀 rate와 제한 보기

풀 rate limit은 6시간 기준으로 계산돼요. 유료 구독이 있는 사용자나 자동화 시스템에는 풀 rate limit이 없어요. Docker Hub를 사용하는 비인증 사용자와 Docker Personal 사용자는 이미지 풀에 rate limit이 적용돼요.

한도를 초과하는 풀을 발행하면 Docker Hub는 매니페스트를 요청할 때 다음 본문과 함께 429 응답 코드를 반환해요:

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

이 오류 메시지는 Docker CLI 또는 Docker Engine 로그에 나타나요.

현재 풀 rate와 제한을 확인하려면:

참고: 제한을 확인하려면 curl과 jq가 설치되어 있어야 해요.

  1. 토큰을 얻어요.
    • 비인증 풀을 하는 경우 익명으로 토큰을 얻으려면:
$ TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
  • 인증된 상태에서 사용자 계정으로 토큰을 얻으려면 다음 명령에 사용자 이름과 비밀번호를 넣어요:
$ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
  1. 제한을 포함하는 헤더를 얻어요. 이 헤더는 GET과 HEAD 요청 모두에서 반환돼요. GET을 사용하면 실제 풀을 에뮬레이션해 제한에 포함되고, HEAD는 그렇지 않아요:
$ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
  1. 헤더를 검사해요. 다음 헤더를 볼 수 있어야 해요:
ratelimit-limit: 100;w=21600
ratelimit-remaining: 20;w=21600
docker-ratelimit-source: 192.0.2.1

위 예시에서 풀 제한은 21600초(6시간)당 100번의 풀이고, 남은 풀은 20번이에요.

ratelimit 헤더가 보이지 않는다면, 게시자, 제공자, 또는 오픈소스 조직과의 파트너십으로 해당 이미지 또는 IP에 제한이 없기 때문일 수 있어요. 또한 풀하는 사용자가 유료 Docker 구독에 속해 있기 때문일 수도 있어요. 이 헤더가 보이지 않으면 그 이미지를 풀해도 풀 rate limit에 포함되지 않아요.

더 알아보기 (Learn more)