Docker 빌드 503 Service Unavailable 에러 해결 (Registry Mirror 설정)

오늘은 도커 빌드 중 아래 문제가 발생하는 경우 해결 방법입니다.

failed to authorize: failed to fetch anonymous token: unexpected status from GET request to https://auth.docker.io/token: 503 Service Unavailable

 

(수정: 이번 문제는 AWS에서 발생한 Outage 이슈로, AWS를 사용 중인 Docker 등 여러 서비스에 영향이 전파된 것으로 보입니다.)

문제 원인 분석

에러 로그에서 auth.docker.io가 503 Service Unavailable 응답을 준 것을 확인할 수 있습니다. 원인은 크게 두 가지로 추측했습니다.

1. Docker Hub 일시적 장애: Docker Hub 인증 서비스에 순간적인 장애가 발생했을 가능성입니다.
2. Rate Limiting: Docker Hub는 익명 사용자에 대해 6시간당 100회의 이미지 pull 제한을 둡니다. 프로덕션 서버에서 이 제한에 도달했을 수 있습니다.

두 경우 모두 프로덕션 배포가 Docker Hub라는 외부 서비스에 강하게 의존하고 있어 발생하는 문제, 즉 SPOF(Single Point of Failure)가 될 수 있는 상황이었습니다.

해결 방법: Docker Registry Mirror 설정

일시적 장애라면 재시도(Retry)로 해결될 수 있고, Rate Limit 문제라면 docker login을 통한 인증으로 해결할 수 있습니다. 하지만 저는 두 가지 문제를 모두 우회하고 향후 더 안정적인 운영을 위해 레지스트리 미러(Registry Mirror)를 설정하는 방법을 선택했습니다.

미러 설정은 Docker Hub 대신 지리적으로 가깝거나 안정적인 미러 서버에서 이미지를 받아오도록 Docker 데몬 설정을 변경하는 것입니다. 저는 Google Container Registry(GCR)에서 제공하는 미러를 사용하기로 했습니다.

설정 방법은 간단합니다.

 

1. /etc/docker/daemon.json 파일 생성 및 수정

daemon.json 파일에 registry-mirrors 항목을 추가합니다.

$ sudo nano /etc/docker/daemon.json

파일 내용은 다음과 같이 작성합니다.

{
    "registry-mirrors": ["https://mirror.gcr.io"]
}

2. Docker 데몬 재시작

설정 파일을 저장한 후, Docker 데몬을 재시작하여 변경 사항을 적용합니다.

sudo systemctl restart docker

3. 빌드 재시도

다시 배포 명령을 실행합니다.

sudo docker compose up -d --build

위와 같이 조치한 결과, Docker Hub가 아닌 mirror.gcr.io를 통해 이미지를 정상적으로 PULL하며 빌드 및 배포가 성공적으로 완료되었습니다.