Amazon Elastic Container Service(Amazon ECS) 작업에서 Amazon Elastic Container Registry(Amazon ECR)의 이미지를 가져올 수 없습니다. 또는 "CannotPullContainerError: API error" 메시지가 표시됩니다.
간략한 설명
다음과 같은 이유로 CannotPullContainerError 오류가 표시될 수 있습니다.
- 인터넷 경로가 없는 프라이빗 서브넷을 사용하므로 시작 유형으로 Amazon ECR 엔드포인트에 액세스할 수 없습니다.
- Amazon ECR 리포지토리 정책이 리포지토리 이미지에 대한 액세스를 제한합니다.
- Amazon ECS 작업 실행 또는 인스턴스 역할에 이미지를 가져올 수 있는 올바른 권한이 없습니다.
- 요청된 이미지 URI가 존재하지 않습니다.
- 디스크에 이미지를 저장할 공간이 충분하지 않습니다.
- 가져오기 속도 할당량을 초과했습니다.
- 작업과 Amazon ECR 엔드포인트 간의 네트워킹 경로가 없습니다.
- Docker 자격 증명이 오래되었습니다.
해결 방법
문제의 원인 파악
AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용하여 문제를 확인합니다. Amazon ECS 클러스터 리소스가 있는 곳과 같은 AWS 리전에서 런북을 실행해야 합니다. 또한 가장 최근에 실패한 작업 ID를 사용하십시오. 실패한 작업이 Amazon ECS 서비스의 일부인 경우, 서비스에서 가장 최근에 실패한 작업을 사용합니다. 실패한 작업은 자동화 중에 ECS:DescribeTasks에 표시되어야 합니다. 기본적으로 중지된 ECS 작업은 중지됨 상태가 된 후 1시간 동안 표시됩니다.
자동화 출력에 따라 다음 수동 문제 해결 단계 중 하나를 사용합니다.
프라이빗 서브넷에 NAT 게이트웨이로 연결되는 경로가 있는지 확인, 또는 PrivateLink 사용
프라이빗 서브넷을 사용하여 Amazon Elastic Compute Cloud(Amazon EC2) 또는 AWS Fargate 시작 유형으로 작업을 실행할 수 있습니다. 두 시작 유형 모두 프라이빗 서브넷의 라우팅 테이블에 NAT 게이트웨이에 대한 경로가 있어야 합니다. 요청을 인터넷으로 라우팅하도록 VPC에서 NAT 게이트웨이를 구성합니다.
또는 AWS PrivateLink를 Amazon ECR 가상 프라이빗 클라우드(VPC) 엔드포인트 및 Amazon Simple Storage Service(Amazon S3) 게이트웨이 엔드포인트에서 사용합니다.
VPC 엔드포인트 보안 그룹은 프라이빗 서브넷 또는 Amazon ECS 작업 VPC에서 포트 443으로 들어오는 연결을 허용해야 합니다.
참고: Windows에서 ECS_IMAGE_PULL_INACTIVITY_TIMEOUT 값은 기본값으로 3분이 설정됩니다. 큰 이미지를 가져오는 경우 3분 내에 이미지 가져오기가 완료되지 않아 요청 시간이 초과될 수 있습니다.
Amazon ECR 리포지토리 정책 확인
Amazon ECR 리포지토리 정책이 리포지토리 이미지에 대한 액세스를 제한하는 경우 403 Forbidden 오류가 표시됩니다. Amazon ECR 리포지토리 정책을 확인하여 리포지토리 이미지 관련 제한이 없는지 확인합니다. 액세스 정책의 예시는 Amazon ECR의 프라이빗 리포지토리 정책 예시를 참조하십시오.
작업 실행 또는 컨테이너 인스턴스 IAM 역할의 권한 확인
Amazon EC2 시작 유형을 사용하는 경우 컨테이너 인스턴스 AWS Identity and Access Management(IAM) 역할에 Amazon ECR 리포지토리에 액세스할 권한이 있는지 확인합니다. AmazonEC2ContainerRegistryReadOnly 정책은 이미지를 가져오는 데 필요한 최소 권한을 제공합니다.
Fargate 시작 유형을 사용하는 경우 이미지를 가져오려면 AmazonECSTaskExecutionRolePolicy가 작업 실행 역할에 연결되어야 합니다.
올바른 IAM 역할을 사용하는지 확인
URI에서 올바른 이미지 이름을 사용하는지 확인하려면 작업 정의의 컨테이너 정의 섹션에서 이미지 파라미터를 확인합니다.
참고: 태그를 기준으로 가져오려면 registry/repository[:tag] 이미지 이름 형식을 사용합니다. 다이제스트를 기준으로 가져오여면 Amazon ECR 리포지토리에서 직접 복사할 수 있는 registry/repository[@digest] 형식을 사용합니다.
디스크 공간 확인
가져온 이미지를 저장할 디스크 공간이 충분하지 않으면 "CannotPullContainerError: no space left on device" 오류 메시지가 표시됩니다. 이 문제를 해결하려면 write /var/lib/docker/tmp/GetImageBlob111111111: no space left on device를 참조하십시오.
가져오기 속도 할당량 초과 여부 확인
Docker Hub를 사용하여 이미지를 가져오고 이미지 가져오기 할당량을 초과하면 "CannotPullContainerError: toomanyrequests: You have reached your pull rate limit" 오류 메시지가 표시됩니다. 가져오기 속도 할당량에 대한 자세한 내용은 Docker Docs 웹사이트의 가져오기 속도 제한을 참조하십시오. 이 문제를 해결하려면 ERROR: toomanyrequests: Too Many Requests or You have reached your pull rate limit를 참조하십시오.
네트워킹 구성 확인
작업과 Amazon ECR 엔드포인트 사이에서 네트워킹 경로가 누락된 경우 다음 예시와 유사한 오류가 표시됩니다.
"Cannotpullcontainererror: error response from daemon"
-또는-
"Client.Timeout exceeded while awaiting headers"
이 문제를 해결하려면 NAT 게이트웨이 또는 PrivateLink를 통해 작업에서 Amazon ECR 리포지토리에 액세스할 수 있는지 확인합니다.
Amazon ECS 서비스를 생성할 때 네트워킹에서 다음 설정을 구성합니다.
- 퍼블릭 서브넷 작업의 경우 퍼블릭 IP에서 퍼블릭 IP 자동 할당을 활성화합니다.
- 프라이빗 서브넷 작업의 경우 퍼블릭 IP 자동 할당을 비활성화하고, NAT 게이트웨이 또는 PrivateLink를 구성합니다.
Docker 로그인 자격 증명 업데이트
Docker 자격 증명이 오래된 경우 "repository does not exist or may require 'docker login'" 오류 메시지가 표시됩니다. 프라이빗 리포지토리 인증을 위한 Docker 로그인 자격 증명을 업데이트하려면 권한 부여 토큰 사용을 참조하십시오.
관련 정보
Amazon ECS의 CannotPullContainer 오류