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

4분 분량

Amazon Elastic Container Registry(Amazon ECR)로 이미지를 풀하면 다음 오류가 발생합니다. "CannotPullContainerError: API error."

간단한 설명

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

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

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

시작에 실패한 Amazon ECS 작업의 오류를 해결하려면 AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용하세요. 그런 다음 문제에 대한 관련 문제 해결 단계를 참조하세요.

해결 방법

중요:

ECS 클러스터 리소스가 위치한 동일한 AWS 리전에서 AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용합니다.
런북을 사용할 때는 가장 최근에 실패한 작업 ID를 사용해야 합니다. 실패한 작업이 Amazon ECS 서비스의 일부인 경우 해당 서비스에서 가장 최근에 실패한 작업을 사용합니다. 실패한 작업은 자동화 중에 ECS:DescribeTasks에 표시되어야 합니다. 기본적으로 중지된 ECS 작업은 중지됨 상태로 전환된 후 1시간 동안 표시됩니다. 가장 최근에 실패한 작업 ID를 사용하면 작업 상태 정리가 자동화 중에 분석을 중단하는 것을 방지할 수 있습니다.

런북을 시작하는 방법에 대한 지침은 AWSSupport-TroubleshootECSTaskFailedToStart를 참조하세요. 자동화 결과에 따라 다음 수동 문제 해결 단계 중 하나를 사용하세요.

시작 유형이 Amazon ECR 엔드포인트에 액세스할 수 없음

1. Amazon Elastic Compute Cloud(Amazon EC2) 시작 유형으로 작업을 실행하고 있고 컨테이너 인스턴스가 프라이빗 서브넷에 있을 수 있습니다. 또는 프라이빗 서브넷에서 AWS Fargate 시작 유형을 사용하여 작업을 실행하고 있을 수도 있습니다. 두 경우 모두 서브넷의 라우팅 테이블에 NAT 게이트웨이로 연결되는 경로가 있는지 확인하세요.

2. 작업에 EC2 시작 유형이 있고 컨테이너 인스턴스가 퍼블릭 서브넷에 있는 경우 인스턴스에 퍼블릭 IP 주소가 있어야 합니다.

-또는-

퍼블릭 서브넷에서 Fargate 시작 유형을 사용하여 작업을 실행하는 경우, 작업을 시작할 때 퍼블릭 IP 자동 할당을 활성화됨으로 선택합니다. 이렇게 하면 작업이 이미지를 가져오기 위한 아웃바운드 네트워크 액세스 권한을 가질 수 있습니다.

3. VPC에서 요청을 인터넷으로 라우팅하도록 NAT 게이트웨이를 구성합니다.
참고: NAT 게이트웨이 대신 AWS PrivateLink를 사용할 수 있습니다.

4. Amazon ECR용 AWS PrivateLink를 사용하는 경우 Amazon ECR용 VPC 엔드포인트와 연결된 보안 그룹의 구성을 확인하세요. VPC CIDR, 컨테이너 인스턴스 또는 Fargate 작업 또는 서비스의 보안 그룹 내에서 HTTPS(포트 443)를 통한 인바운드 트래픽을 허용해야 합니다.

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

Amazon ECR 리포지토리 정책이 리포지토리 이미지에 대한 액세스를 제한함

Amazon ECR 리포지토리 정책에서 리포지토리 액세스에 대한 제한 사항을 확인합니다. 다음 리포지토리 정책 예시에서는 IAM 사용자가 이미지를 가져오고 내보낼 수 있습니다.

{  "Version": "2012-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"
      ]
    }
  ]
}

IAM 역할에 이미지를 가져오기 위한 적절한 권한이 없음

EC2 시작 유형으로 작업을 실행하는 경우 인스턴스 프로파일과 연결된 인스턴스 IAM 역할에 대한 권한을 확인하세요. Amazon ECR 리포지토리에 액세스할 권한이 있어야 합니다.

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

Fargate 시작 유형을 사용하여 작업을 실행하는 경우 AmazonECSTaskExecutionRolePolicy에 필요한 권한이 있는지 확인합니다.

이미지를 찾을 수 없음

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

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

Amazon VPC 게이트웨이 엔드포인트 정책에 의해 Amazon S3 액세스가 거부됨

라우팅 테이블에 Amazon S3용 Amazon VPC 게이트웨이 엔드포인트에 대한 경로가 있는 경우 다음 단계를 완료합니다.

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

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