Amazon ECR 사용 시 Docker 명령과 문제 해결

어떤 경우에는 Amazon ECR에 대해 Docker 명령을 실행하면 오류 메시지가 나타날 수 있습니다. 일반적인 오류 메시지와 잠재적 해결 방법은 아래에 설명되어 있습니다.

Docker 로그에 예상된 오류 메시지가 포함되지 않음
Amazon ECR 리포지토리에서 이미지를 풀할 때 "Filesystem Verification Failed" 또는 "404: Image Not Found" 오류
Amazon ECR에서 이미지를 풀할 때 "Filesystem Layer Verification Failed" 오류
리포지토리에 푸시할 때 HTTP 403 오류 또는 "no basic auth credentials" 오류

출처: 문서

본문

Docker 로그에 예상된 오류 메시지가 포함되지 않음

Docker 관련 문제 디버깅을 시작하려면 먼저 호스트 인스턴스에서 실행되는 Docker 데몬의 디버깅 출력을 켜세요. Amazon ECS 컨테이너 인스턴스에서 Amazon ECR로부터 풀한 이미지를 사용한다면, Amazon Elastic Container Service 개발자 가이드의 Configuring verbose output from the Docker daemon을 참조하세요.

Amazon ECR 리포지토리에서 이미지를 풀할 때 "Filesystem Verification Failed" 또는 "404: Image Not Found" 오류

Docker 1.9 이상을 사용할 때 docker pull 명령으로 Amazon ECR 리포지토리에서 이미지를 풀하면 Filesystem verification failed 오류가 발생할 수 있습니다. Docker 1.9 이전 버전을 사용할 때는 404: Image not found 오류가 발생할 수 있습니다. 몇 가지 가능한 원인과 그 설명은 아래에 나와 있습니다.

로컬 디스크가 가득 참

docker pull을 실행하는 로컬 디스크가 가득 차 있다면, 로컬 파일에서 계산된 SHA-1 해시가 Amazon ECR이 계산한 것과 다를 수 있습니다. 풀하려는 Docker 이미지를 저장할 수 있을 만큼 로컬 디스크에 여유 공간이 있는지 확인하세요. 새 이미지를 위한 공간을 만들기 위해 오래된 이미지를 삭제할 수도 있습니다. docker images 명령을 사용하여 로컬에 다운로드된 모든 Docker 이미지 목록과 그 크기를 확인할 수 있습니다.

네트워크 오류로 클라이언트가 원격 리포지토리에 연결할 수 없음

Amazon ECR 리포지토리에 대한 호출은 인터넷에 대한 정상적인 연결이 필요합니다. 네트워크 설정을 확인하고 다른 도구와 애플리케이션이 인터넷의 리소스에 접근할 수 있는지 확인하세요. 프라이빗 서브넷의 Amazon EC2 인스턴스에서 docker pull을 실행한다면, 서브넷이 인터넷으로 가는 경로를 가지고 있는지 확인하세요. NAT(네트워크 주소 변환) 서버 또는 관리형 NAT 게이트웨이를 사용하세요.

현재 Amazon ECR 리포지토리에 대한 호출은 회사 방화벽을 통한 Amazon Simple Storage Service(Amazon S3)에 대한 네트워크 접근도 필요합니다. 조직이 서비스 엔드포인트를 허용하는 방화벽 소프트웨어나 NAT 디바이스를 사용한다면, 현재 리전의 Amazon S3 서비스 엔드포인트가 허용되도록 확인하세요.

HTTP 프록시 뒤에서 Docker를 사용한다면, Docker에 적절한 프록시 설정을 구성할 수 있습니다. 자세한 내용은 Docker 문서의 HTTP proxy를 참조하세요.

Amazon ECR에서 이미지를 풀할 때 "Filesystem Layer Verification Failed" 오류

docker pull 명령으로 이미지를 풀할 때 image image-name not found 오류가 발생할 수 있습니다. Docker 로그를 검사하면 다음과 같은 오류가 표시될 수 있습니다.

filesystem layer verification failed for digest sha256:2b96f...

이 오류는 이미지의 레이어 중 하나 이상이 다운로드에 실패했음을 나타냅니다. 몇 가지 가능한 원인과 그 설명은 아래에 나와 있습니다.

이전 버전의 Docker 사용

이 오류는 Docker 1.10 미만 버전을 사용할 때 소수의 경우에 발생할 수 있습니다. Docker 클라이언트를 1.10 이상으로 업그레이드하세요.

클라이언트가 네트워크 또는 디스크 오류를 겪음

앞서 Filesystem verification failed 메시지에서 논의한 것처럼, 디스크가 가득 차거나 네트워크 문제로 인해 하나 이상의 레이어가 다운로드되지 않을 수 있습니다. 위의 권장 사항을 따라 파일시스템이 가득 차지 않았는지 확인하고 네트워크 내에서 Amazon S3에 접근할 수 있게 하세요.

리포지토리에 푸시할 때 HTTP 403 오류 또는 "no basic auth credentials" 오류

aws ecr get-login-password 명령으로 Docker에 성공적으로 인증했음에도 불구하고 docker push 또는 docker pull 명령에서 HTTP 403(Forbidden) 오류 또는 no basic auth credentials 오류 메시지가 발생하는 경우가 있습니다. 이 문제의 몇 가지 알려진 원인은 다음과 같습니다.

다른 리전에 인증했음

인증 요청은 특정 리전에 연결되어 있으며 리전 간에 사용할 수 없습니다. 예를 들어 미국 서부(오레곤)에서 인증 토큰을 얻었다면, 그 토큰을 사용해 미국 동부(버지니아 북부)의 리포지토리에 인증할 수 없습니다. 이 문제를 해결하려면 리포지토리가 존재하는 동일한 리전에서 인증 토큰을 검색했는지 확인하세요. 자세한 내용은 Private registry authentication in Amazon ECR을 참조하세요.

권한이 없는 리포지토리에 푸시하도록 인증했음

리포지토리에 푸시할 필요한 권한이 없을 수 있습니다. 자세한 내용은 Private repository policies in Amazon ECR을 참조하세요.

토큰이 만료되었음

GetAuthorizationToken 작업으로 얻은 토큰의 기본 인증 토큰 만료 기간은 12시간입니다.

wincred 자격 증명 관리자의 버그

Docker for Windows의 일부 버전은 wincred이라는 자격 증명 관리자를 사용하는데, 이는 aws ecr get-login-password가 출력한 docker login 명령을 제대로 처리하지 못합니다(자세한 내용은 CredsStore fails with private repositories 참조). 출력된 docker login 명령을 실행할 수는 있지만, 이미지를 푸시하거나 풀하려고 하면 그 명령들이 실패합니다. 이 버그를 해결하려면 aws ecr get-login-password가 출력한 docker login 명령의 레지스트리 인수에서 https:// 스킴을 제거하세요. HTTPS 스킴이 없는 예제 docker login 명령은 아래와 같습니다.

docker login -u AWS -p <password> <aws_account_id>.dkr.ecr.<region>.amazonaws.com