如何解决在 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 任务在进入 Stopped（已停止）状态后 1 小时内可见。

要启动运行手册，请参阅 AWSSupport-TroubleshootECSTaskFailedToStart。根据自动化的输出，使用以下解决方法之一。

**重要事项：**在与您的 Amazon ECS 集群资源所在的同一 AWS 区域使用 AWSSupport-TroubleshootECSTaskFailedToStart 运行手册。

您的 Amazon ECS 容器实例网络配置不正确

如果您的 Amazon ECS 容器实例没有互联网连接，则该实例无法访问 Amazon Elastic Container Registry (Amazon ECR) 端点。如果未与端点建立连接，实例就无法拉取映像。要验证您的 Amazon ECS 容器实例是否可以访问互联网，请执行以下操作：

• 确认您的实例可以通过互联网网关或 NAT 网关访问互联网。要对 NAT 网关连接问题进行故障排除，请参阅为什么我无法使用 NAT 将私有子网中的 EC2 实例连接到互联网？
  **注意：**您可以使用 AWS PrivateLink 来代替 NAT 网关。为避免错误，请确保正确配置 PrivateLink。
• 验证是否允许在实例、安全组和网络访问控制列表级别，通过端口 443 进行入站 HTTPS 访问。要对互联网网关连接问题进行故障排除，请参阅为什么我的 Amazon EC2 实例无法通过互联网网关访问互联网？
• 如果您使用虚拟私有云 (VPC) 端点连接到 Amazon ECR 端点，请检查您的 Amazon ECS 容器实例安全组。允许您的 Amazon ECS 容器实例向您的 VPC 端点的安全组发送流量。
• 如果您收到错误消息 CannotPullContainerError: API error，请参阅如何解决 Amazon ECS 任务无法从 Amazon ECR 拉取映像的问题？

您的 IAM 角色没有拉取映像的权限

确认与实例配置文件关联的实例 IAM 角色有权访问 Amazon ECR 存储库。

**注意：**AWS 托管式策略 AmazonEC2ContainerRegistryReadOnly 提供拉取映像所需的最低权限。

已达到 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**"

要解决此问题，请验证任务定义中 image（映像）字段的值是否正确。确认相应的存储库和标签存在于您要从中拉取的容器注册表中。

如果您的任务从 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 映像存储库中推送或拉取映像？

文件系统已满

如果您的文件系统已满，那么您会收到以下错误：

"CannotPullContainerError: write /var/lib/docker/tmp/GetImageBlob2923440728: no space left on device"

要解决此问题，请执行以下操作：

• 配置Amazon ECS 任务和映像自动清理。
• 增加容器实例的磁盘大小。