如何解决 Amazon ECS 任务无法从 Amazon ECR 拉取映像的问题？

简短描述

由于以下原因，您可能会收到 CannotPullContainerError：

• 您使用的私有子网没有通往互联网的路由，因此您的启动类型无权访问 Amazon ECR 端点。
• 您的 Amazon ECR 存储库策略限制了对存储库映像的访问。
• 您的 Amazon ECS 任务执行或实例角色没有拉取映像的正确权限。
• 请求的映像 URI 不存在。
• 磁盘上没有足够的空间存放映像。
• 超过了拉取速率配额。
• 您的任务和 Amazon ECR 端点之间缺少联网路径。
• 您的 Docker 凭证已过时。

解决方法

确定问题的原因

使用 AWSSupport-TroubleshootECSTaskFailedToStart 运行手册来确定问题。您必须在您的 Amazon ECS 集群资源所在的 AWS 区域使用运行手册。另外，使用最近失败的任务的 ID。如果失败的任务是 Amazon ECS 服务的一部分，则使用服务中最近一次失败的任务。在自动化执行期间，失败任务必须在 ECS:DescribeTasks 中可见。默认情况下，已停止的 ECS 任务将在进入 Stopped（已停止）状态后的 1 小时内保持可见。

根据自动化的输出，使用以下任一手动故障排除步骤。

确保您的私有子网有指向 NAT 网关的路由，或者使用 PrivateLink

您可以使用私有子网运行具有 Amazon Elastic Compute Cloud (Amazon EC2) 或 AWS Fargate 启动类型的任务。对于这两种启动类型，确保私有子网的路由表中有指向 NAT 网关的路由。在 VPC 中配置 NAT 网关，以便将请求路由到互联网。

或者，将 AWS PrivateLink 与 Amazon ECR 虚拟私有云 (VPC) 端点和 Amazon Simple Storage Service (Amazon S3) 网关端点配合使用。

VPC 端点安全组必须允许端口 443 上来自私有子网或 Amazon ECS 任务 VPC 的传入连接。

**注意：**Windows 中的 ECS_IMAGE_PULL_INACTIVITY_TIMEOUT 值设置为默认值 3 分钟。如果您要拉取大映像，则映像拉取可能无法在 3 分钟内完成，并且请求会超时。

查看您的 Amazon ECR 存储库策略

如果您的 Amazon ECR 存储库策略限制了对存储库映像的访问，则会收到 403 Forbidden（403 禁止）错误。查看您的 Amazon ECR 存储库策略，确保对存储库映像没有限制。有关访问策略的示例，请参阅 Amazon ECR 中的私有存储库策略示例。

检查您的任务执行或容器实例 IAM 角色的权限

如果您使用 Amazon EC2 启动类型，请确保容器实例 AWS Identity and Access Management (IAM) 角色有权访问 Amazon ECR 存储库。AmazonEC2ContainerRegistryReadOnly 策略提供了拉取映像所需的最低权限。

如果您使用 Fargate 启动类型，请确保 AmazonECSTaskExecutionRolePolicy 已附加到任务执行角色，这样才能拉取映像。

务必使用正确的映像 URI

要确认 URI 中的使用的映像名称正确，请检查任务定义的容器定义部分中的映像参数。

**注意：**要按标签拉取，请使用 registry/repository[:tag] 映像名称格式。要按摘要拉取，请使用 registry/repository[@digest] 格式，您可以直接从 Amazon ECR 存储库复制该格式。

检查您的磁盘空间

如果没有足够的磁盘空间来存储拉取的映像，则会收到“CannotPullContainerError: no space left on device”（CannotPullContainerError：设备上没有剩余空间）错误消息。要解决此问题，请参阅 write /var/lib/docker/tmp/GetImageBlob111111111: no space left on device（写入 /var/lib/docker/tmp/GetImageBlob111111111：设备上没有剩余空间）。

检查是否超过了拉取速率配额

如果您使用 Docker Hub 来拉取映像并超过映像拉取配额，则会收到“CannotPullContainerError: toomanyrequests: You have reached your pull rate limit”（CannotPullContainerError: toomanyrequests：您已达到拉取速率限制）错误消息。有关拉取速率配额的信息，请参阅 Docker 文档网站上的 Pull rate limit。要解决此问题，请参阅 ERROR: toomanyrequests: Too Many Requests or You have reached your pull rate limit（错误：请求过多：请求过多或者您已达到拉取速率限制）。

检查您的网络配置

如果您的任务和 Amazon ECR 端点之间缺少联网路径，则会收到与以下示例类似的错误：

“Cannotpullcontainererror: error response from daemon”（Cannotpullcontainererror：来自进程守护程序的错误响应）

-或-

“Client.Timeout exceeded while awaiting headers”（等待标头时已超过 Client.Timeout）

要解决此问题，请检查您的任务是否可以通过 NAT 网关或 PrivateLink 访问 Amazon ECR 存储库。

创建 Amazon ECS 服务时，请在 Networking（网络）下配置以下设置：

• 对于公共子网中的任务，在 Public IP（公有 IP）中，激活 Auto-assign public IP（自动分配公有 IP）。
• 对于私有子网中的任务，停用 Auto-assign public IP（自动分配公有 IP），然后配置 NAT 网关或 PrivateLink。

更新您的 Docker 登录凭证

如果您的 Docker 凭证已过期，则会收到“repository does not exist or may require 'docker login'”（存储库不存在或可能需要‘docker 登录’）错误消息。要更新用于私有存储库身份验证的 Docker 登录凭证，请参阅使用授权令牌。

相关信息

Amazon ECS 中的 CannotPullContainer 任务错误