如何解决 Amazon ECS 中的 Amazon ECR 错误“CannotPullContainerError： API 错误”？

简短描述

您可能会因以下问题之一收到此错误：

• 您的启动类型无权访问 Amazon ECR 端点
• 您的 Amazon ECR 存储库策略限制了对存储库映像的访问
• 您的 AWS Identity and Access Management（IAM）角色没有拉取或推送映像的正确权限
• 找不到映像
• 您的 Amazon Virtual Private Cloud（Amazon VPC）网关端点策略拒绝了 Amazon Simple Storage Service（Amazon 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 网关以将请求路由到互联网。
**注意：**您可以使用 AWS PrivateLink 作为 NAT 网关的替代方案。

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.    确认 Amazon VPC 网关端点具有访问 S3 存储桶的正确策略。

相关信息

CannotPullContainer 任务错误