Amazon ECS에서 Amazon ECR 오류 "CannotPullContainerError: API error"를 해결하려면 어떻게 해야 하나요?

최종 업데이트 날짜: 2022년 3월 28일

이 오류는 다음 문제 중 하나로 인해 발생할 수 있습니다.

• 사용자의 시작 유형이 Amazon ECR 엔드포인트에 대한 액세스 권한을 보유하지 없음
• 사용자의 Amazon ECR 리포지토리 정책에서 리포지토리 이미지에 대한 액세스를 제한함
• 사용자의 AWS Identity and Access Management(IAM) 역할에 이미지를 가져오기나 내보낼 권한이 없음
• 이 이미지를 찾을 수 없음
• Amazon Simple Storage Service(Amazon S3) 액세스가 Amazon Virtual Private Cloud(Amazon VPC) 게이트웨이 엔드포인트 정책에서 거부됨

이미지를 가져오려면 Amazon ECS가 Amazon ECR 엔드포인트와 통신해야 합니다.

1.    Amazon Elastic Compute Cloud(Amazon EC2) 시작 유형을 사용하여 태스크를 실행하고 컨테이너 인스턴스가 프라이빗 서브넷에 있거나 프라이빗 서브넷에서 AWS Fargate 시작 유형을 사용하여 태스크를 실행하는 경우, 사용자 서브넷이 라우팅 테이블의 NAT 게이트웨이에 대한 경로를 포함하는지 확인합니다.

2.    EC2 시작 유형을 사용하여 태스크를 실행 중이고 컨테이너 인스턴스가 퍼블릭 서브넷에 있는 경우 인스턴스에 퍼블릭 IP 주소가 있는지 확인합니다.

-또는-

퍼블릭 서브넷에서 Fargate 시작 유형을 사용하여 태스크를 실행하는 경우 태스크를 시작할 때 퍼블릭 IP 자동 할당에 대해 [활성화됨(ENABLED)]을 선택합니다. 이렇게 하면 태스크가 아웃바운드 네트워크 액세스를 통해 이미지를 가져올 수 있습니다.

3.    인터넷에 요청을 라우팅하도록 VPC에서 NAT 게이트웨이를 구성합니다.

참고: AWS PrivateLink를 NAT 게이트웨이의 대안으로 사용할 수 있습니다.

4.    AWS PrivateLink for Amazon ECR을 사용할 경우 Amazon ECR용 인터페이스 VPC 엔드포인트와 연결된 보안 그룹에서 VPC CIDR, ECS 컨테이너 인스턴스 또는 Fargate 태스크 또는 서비스의 보안 그룹 내에서 HTTPS(포트 443)를 통한 인바운드 트래픽을 허용하는지 확인합니다.

5.    인스턴스 및 Fargate 태스크와 연결된 보안 그룹에서 HTTPS(포트 443), DNS(UDP 및 TCP, 포트 53 사용), 서브넷 네트워크 액세스 제어 목록(네트워크 ACL)에 대해 아웃바운드 액세스를 허용하는지 확인합니다.

Amazon ECR 리포지토리 정책에서 리포지토리 액세스에 대한 제한 사항을 확인합니다.

다음 리포지토리 정책 예제에서는 IAM 사용자가 이미지를 가져오고 내보낼 수 있습니다.

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "AllowPushPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/push-pull-user-1",
          "arn:aws:iam::123456789012:user/push-pull-user-2"
        ]
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload"
      ]
    }
  ]
}

EC2 시작 유형을 사용하여 태스크를 실행하는 경우 인스턴스 프로파일에 연결된 인스턴스 IAM 역할이 Amazon ECR 리포지토리에 액세스할 권한을 보유하는지 확인합니다.

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

Fargate 시작 유형을 사용하여 태스크를 실행하는 경우 AmazonECSTaskExecutionRolePolicy가 필요한 권한을 보유하는지 확인합니다.

URI에서 올바른 이미지 이름을 확인하려면 작업 정의의 컨테이너 정의 섹션에서 이미지 파라미터를 확인합니다.

참고: 태그를 기준으로 가져오려면 registry/repository[:tag]와 같은 이미지 이름 형식을 사용합니다. 다이제스트를 기준으로 가져오려면 registry/repository[@digest] 형식을 사용합니다.

라우팅 테이블에 Amazon S3의 Amazon VPC 게이트웨이 엔드포인트에 대한 경로가 있는 경우 다음을 수행합니다.

1.    Amazon VPC 게이트웨이 엔드포인트의 액세스 정책을 확인합니다.

2.    S3 버킷에 액세스할 수 있도록 Amazon VPC 게이트웨이 엔드포인트에 올바른 정책이 있는지 확인합니다.