Amazon ECS에서 EC2 작업을 시작할 때 ‘CannotPullContainerError’ 오류를 해결하려면 어떻게 해야 합니까?

간략한 설명

CannotPullContainerError는 다음과 같은 이유로 발생합니다.

• 네트워크를 잘못 구성했기 때문에 Amazon EC2 시작 유형 작업은 이미지를 가져올 수 없습니다.
• AWS Identity and Access Management(IAM) 역할에는 이미지를 가져올 권한이 없습니다.
• DockerHub 속도 할당량에 도달했습니다.
• 이미지 이름 또는 태그가 존재하지 않습니다.
• 작업 정의는 다른 AWS 계정에 있는 이미지를 참조합니다.

해결 방법

AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용하여 문제 해결

시작하지 못한 Amazon ECS 작업의 문제를 해결하려면 AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용하십시오. 런북을 실행할 때는 가장 최근에 실패한 작업 ID를 사용해야 합니다. 실패한 작업이 Amazon ECS 서비스의 일부인 경우, 서비스에서 가장 최근에 실패한 작업을 사용합니다. 실패한 작업은 자동화 중에 ECS:DescribeTasks에 표시되어야 합니다. 기본적으로 Amazon ECS 작업은 중지됨 상태가 된 후 1시간 동안 표시됩니다.

런북을 시작하려면 AWSSupport-TroubleshootECSTaskFailedToStart를 참조하십시오. 자동화 출력에 따라 다음 해결 방법 중 하나를 사용합니다.

중요: Amazon ECS 클러스터 리소스가 위치한 AWS 리전과 동일한 리전에 AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용합니다.

Amazon ECS 컨테이너 인스턴스 네트워크 구성이 올바르지 않음

Amazon ECS 컨테이너 인스턴스가 인터넷에 연결되어 있지 않으면 인스턴스가 Amazon Elastic Container Registry(Amazon ECR) 엔드포인트에 연결할 수 없습니다. 엔드포인트에 연결되지 않으면 인스턴스가 이미지를 가져올 수 없습니다. Amazon ECS 컨테이너 인스턴스가 인터넷에 액세스할 수 있는지 확인하려면 다음 작업을 수행하십시오.

• 인스턴스가 인터넷 게이트웨이 또는 NAT 게이트웨이를 통해 인터넷에 액세스할 수 있는지 확인합니다. NAT 게이트웨이 연결 문제를 해결하려면 다음 문서를 참조하십시오. 프라이빗 서브넷의 Amazon EC2 인스턴스가 NAT 게이트웨이를 사용하여 인터넷에 연결할 수 없는 이유는 무엇입니까?
  참고: NAT 게이트웨이 대신 AWS PrivateLink를 사용할 수 있습니다. 오류를 방지하려면 AWS PrivateLink를 올바르게 구성해야 합니다.
• 인스턴스, 보안 그룹 및 네트워크 액세스 제어 목록(네트워크 ACL) 수준에서 포트 443을 통해 인바운드 HTTPS 액세스가 허용되는지 확인합니다. 인터넷 게이트웨이 연결 문제를 해결하려면 Amazon EC2 인스턴스가 인터넷 게이트웨이를 통해 인터넷에 액세스할 수 없는 이유는 무엇입니까?를 참조하십시오.
• 가상 프라이빗 클라우드(VPC) 엔드포인트를 사용하여 Amazon ECR 엔드포인트에 연결하는 경우, Amazon ECS 컨테이너 인스턴스 보안 그룹을 확인하십시오. Amazon ECS 컨테이너 인스턴스가 VPC 엔드포인트의 보안 그룹에 트래픽을 전송하도록 허용합니다.
• CannotPullContainerError: API error라는 오류 메시지가 표시되는 경우 Amazon ECS 작업이 Amazon ECR의 이미지를 가져오지 못하는 문제를 해결하려면 어떻게 해야 합니까?를 참조하십시오.

IAM 역할에 이미지를 가져올 권한이 없음

인스턴스 프로파일과 연결된 인스턴스 IAM 역할에 Amazon ECR 리포지토리에 액세스할 권한이 있는지 확인합니다.

참고: AmazonEC2ContainerRegistryReadOnly AWS 관리형 정책은 이미지를 가져오는 데 필요한 최소 권한을 제공합니다.

DockerHub 가져오기 속도 한도에 도달함

DockerHub에서 이미지를 가져오려고 하는데 가져오기 속도 할당량에 도달한 경우 다음 오류 메시지가 표시됩니다.

"CannotPullContainerError: inspect image has been retried 5 time(s): httpReaderSeeker: failed open: unexpected status code https://registry-1.docker.io/v2/manifests/sha256:2bb501e6429 Too Many Requests - Server message: toomanyrequests:"

이 문제를 해결하려면 Amazon ECS에서 "CannotPullContainerError: You have reached your pull rate limit" 오류를 해결하려면 어떻게 해야 합니까?를 참조하십시오.

이미지 이름 또는 태그가 존재하지 않음

Amazon ECR에 호스팅된 이미지 또는 태그를 정의했지만 해당 이미지 또는 태그가 존재하지 않는 경우, 다음과 같은 오류 메시지가 나타납니다.

"Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref 123456789.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: 123456789**.dkr.ecr.ap-southeast-2.amazonaws.com/image-name:tag: not found**"

이 문제를 해결하려면 작업 정의에서 이미지 필드의 값이 올바른지 확인하십시오. 가져오려는 컨테이너 레지스트리에 해당 리포지토리와 태그가 있는지 확인합니다.

작업이 Amazon ECR이 아닌 레지스트리에서 이미지를 가져오고 작업에 정보가 누락된 경우 다른 오류가 발생합니다. 이미지가 없거나, 태그가 없거나, 레지스트리 자격 증명이 제공되지 않은 경우 다음 오류가 발생합니다.

"Cannotpullcontainererror: pull image manifest has been retried 1 time(s): failed to resolve ref docker.io/library/invalid-name:non-existenttag: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed"

이 문제를 해결하려면 작업 정의에서 이미지 필드를 확인하십시오. 해당 컨테이너 레지스트리에 이미지가 있는지 확인합니다. 이미지가 있는 경우 올바른 자격 증명을 제공해야 합니다. 자세한 내용은 Amazon ECS에서 비 AWS 컨테이너 이미지 사용을 참조하십시오.

작업 정의에 참조된 이미지가 다른 계정에 있음

이미지가 다른 계정에 있는 경우 다음과 같은 오류 메시지가 나타날 수 있습니다.

"Cannotpullcontainererror: pull access denied for 123456789***.dkr.ecr.us-east-1.amazonaws.com/image-name:tag, repository does not exist or may require 'docker login': denied: User: arn:aws:sts::012345678**:assumed-role/role-name/ec2 instance id is not authorized to perform: ecr:BatchGetImage on resource: arn:aws:ecr:us-east-1:123456789*:repository/image-name:tag because no resource-based policy allows the ecr:BatchGetImage action"

이 문제를 해결하려면 이미지가 있는 계정의 리포지토리 정책에서 ecr:batchGetImage 작업을 허용해야 합니다.

예를 들어 Amazon ECS 클러스터와 연결된 인스턴스는 계정 A에 있고 작업 정의는 계정 B의 이미지를 참조합니다. 계정 B의 리포지토리 정책은 계정 A의 인스턴스 IAM 역할에 대해 ecr:batchGetImage를 허용해야 합니다. 또한 리포지토리 정책에서 교차 계정 권한을 활성화해야 합니다. 그런 다음, 계정 A의 인스턴스가 계정 B의 이미지를 가져올 수 있는지 확인합니다. 자세한 내용은 보조 계정이 Amazon ECR 이미지 리포지토리의 이미지를 푸시하거나 가져오도록 하려면 어떻게 해야 합니까?를 참조하십시오.