如何对 Amazon ECS 中的“无法拉取密钥或注册表身份验证”错误进行故障排除？

简短描述

AWS Fargate 平台版本 1.4.0 使用任务弹性网络接口来拉取映像和密钥。所有网络流量都流经您的 Amazon Virtual Private Cloud（Amazon VPC）内的弹性网络接口。您可以通过 Amazon VPC 流日志查看此流量。但该任务使用您的网络配置，而不是使用 Fargate 拥有的弹性网络接口。这是因为弹性网络接口位于您的 Amazon VPC 中。

Amazon ECS 容器代理使用任务执行 AWS Identity and Access Management（IAM）角色来从以下服务获取信息：

• AWS Systems Manager Parameter Store
• AWS Secrets Manager

如果您使用客户托管的 AWS Key Management Service（AWS KMS）密钥来加密数据，请向任务执行 IAM 角色授予以下权限：

• ssm:GetParameters
• secretsmanager:GetSecretValue
• kms:Decrypt。

通过 AWSSupport-TroubleshootECSTaskFailedToStart 运行手册，对无法启动的 Amazon ECS 任务进行故障排除。此自动化会审查以下配置：

• 与已配置容器注册表的网络连接
• 缺少任务执行角色所需的 IAM 权限
• 虚拟私有云（VPC）端点连接
• 安全组规则配置
• AWS Secrets Manager 密钥参考
• 日志配置

如果运行手册的输出未提供建议，请使用下一节中的手动故障排除法。

解决方法

重要事项：

• 在您的 ECS 集群资源所在的 AWS 区域使用运行手册。
• 使用运行手册时，必须使用最近失败的任务 ID。如果失败的任务是 Amazon ECS 服务的一部分，则在服务中使用最近失败的任务。在自动化执行期间，失败的任务必须在 ECS:DescribeTasks 中可见。默认情况下，已停止的 ECS 任务在进入已停止状态后的 1 小时内保持可见。使用最近失败的任务 ID 可防止任务状态清理功能在自动化过程中导致分析中断。

要运行 AWSSupport-TroubleshootECSTaskFailedToStart 运行手册，请完成以下步骤：

1. 打开 AWS Systems Manager 控制台。
2. 在导航窗格的变更管理下，选择自动化。
3. 选择执行自动化。
4. 选择由 Amazon 所有选项卡。
5. 在自动化文档下，搜索 TroubleshootECSTaskFailedToStart。
6. 选择 AWSSupport-TroubleshootECSTaskFailedToStart 卡。
   **注意：**确保选择卡上的单选按钮，而不是超链接的自动化名称。
7. 选择下一步。
   注意：执行后，分析结果将填充到全局输出部分。但是，请等待文档状态变为成功。此外，请注意输出部分中的任何异常。
8. 对于执行自动化文档，选择简单执行。
9. 在输入参数部分，对于 AutomationAssumeRole，输入允许 Systems Manager Automation 执行操作的角色的 ARN。
   **注意：**确保 AutomationAssumeRole 或 IAM 用户或角色具有运行 AWSSupport-TroubleshootECSTaskFailedToStart 运行手册所需的 IAM 权限。如果您没有指定 IAM 角色，Systems Manager Automation 将使用运行运行手册的 IAM 用户或角色的权限。有关为 Systems Manager Automation 创建代入角色的详细信息，请参阅任务 1： 为自动化创建服务角色。
10. 对于 ClusterName，输入任务启动失败的群集名称。
11. 对于 TaskId，请输入最近失败的任务的标识。
12. 选择执行。

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

检查从您的子网到互联网的路由

如果您在公有子网中有 Fargate 任务，请验证您的任务是否已分配公有 IP 地址。此外，确认任务有通往互联网网关的默认路由（0.0.0.0/0）。当您启动新任务或创建新服务时，请启用自动分配公有。

如果使用以下配置，则不要使用公有子网中的互联网网关来访问 Secrets Manager 或 Systems Manager。而是使用 Amazon VPC 端点：

• Secrets Manager 或 Systems Manager VPC 端点位于公有子网中。
• 您在 Amazon VPC DHCP 设置中启用了 AmazonProvidedDNS。

注意：您无法为现有任务启用自动分配公有。对于现有服务，您只能使用 AWS 命令行界面（AWS CLI）来重新配置服务。您不能使用 AWS 管理控制台。如果您使用 AWS CloudFormation 堆栈创建 Amazon ECS 服务，请修改 NetworkConfiguration 属性 AWS::ECS::Service 来更新该服务。

如果您在私有子网中有 Fargate 任务，请验证您的任务是否有通往互联网连接源的默认路由（0.0.0.0/0）。互联网连接源可以是 NAT 网关、AWS PrivateLink 或其他来源。

• 如果您使用 NAT 网关，请将 NAT 网关放置于公有子网中。有关详细信息，请参阅使用互联网网关和 NAT 网关的架构。
• 如果您使用 PrivateLink，请确保您的 Fargate 基础设施可以使用您的 Amazon VPC 端点的安全组。
• 如果您使用自定义域名服务器，请确认 DNS 查询的设置。查询必须使用 UDP 和 TCP 协议，在端口 53 上具有出站访问权限。此外，它必须在端口 443 上具有 HTTPS 访问权限。

检查网络 ACL 和安全组设置

确认网络访问控制列表（网络 ACL）和安全组不会阻止子网对端口 443 的出站访问。有关详细信息，请参阅使用安全组控制流向资源的流量。

**注意：**Fargate 任务必须具有端口 443 的出站访问权限，才能允许传出流量并访问 Amazon ECS 端点。

检查您的 Amazon VPC 端点

如果您使用 PrivateLink，则必须创建所需的端点。

Fargate 平台版本 1.4.0 或更高版本需要以下端点：

• com.amazonaws.region.ecr.dkr
• com.amazonaws.region.ecr.api
• S3 网关端点
• com.amazonaws.region.logs

有关详细信息，请参阅 ](https://docs.aws.amazon.com/AmazonECR/latest/userguide/vpc-endpoints.html#ecr-vpc-endpoint-considerations)Amazon ECR VPC 端点注意事项[。

注意： 如果您的任务定义使用 Secrets Manager、Systems Manager 参数或 Amazon CloudWatch Logs，则可能需要定义端点。有关详细信息，请参阅以下文档：

• 使用 AWS Secrets Manager VPC 端点
• 为 Amazon ECS 创建 VPC 端点
• 将 CloudWatch Logs 与接口 VPC 端点配合使用

如果您使用 PrivateLink，请检查 Amazon VPC 的安全组是否允许正确的流量。该组必须在 TCP 端口 443 上允许来自 Fargate 任务安全组或 Fargate 任务 VPC CIDR 范围的流量。

要确认 Fargate 基础设施具有服务访问权限，请检查 VPC 端点策略与 Amazon Simple Storage Solution（Amazon S3）的端点策略。

检查您的 IAM 角色和权限

任务执行角色向 Amazon ECS 容器和 Fargate 代理授予对任务进行 API 调用所需的权限。当您执行以下操作时，Fargate 需要此角色：

• 从 Amazon Elastic Container Registry（Amazon ECR）拉取容器映像。
• 使用 awslogs 日志驱动程序。
• 使用私有注册表身份验证。
• 使用 Secrets Manager 密钥或 Systems Manager Parameter Store 参数来引用敏感数据。

如果您的用例涉及上述任何场景，则在您的任务执行角色中定义所需的权限。有关所需权限的完整列表，请参阅 Amazon ECS 任务执行 IAM 角色。

检查 Amazon ECS 任务定义中引用的敏感信息

检查密钥和参数名称是否与 Amazon ECS 任务定义中的引用名称相匹配。然后，检查任务定义中容器定义中的值是否与您的 Amazon ECS 任务定义中的值相匹配。有关详细信息，请参阅如何将密钥或敏感信息安全地传递给 Amazon ECS 任务中的容器？

如果 Systems Manager Parameter Store 参数和任务位于同一区域，则使用完整的 ARN 或密钥名称。如果参数存在于其他区域，则必须指定完整的 ARN。

要检查 Systems Manager 参数名称和 ARN，请完成以下步骤：

**注意：**如果在运行 AWS CLI 命令时出现错误，请确保您使用的是最新版本的 AWS CLI。

1. 打开 AWS Systems Manager 控制台。
2. 在导航窗格中，选择 Parameter Store，然后确认您的 Parameter Store 名称。
3. 要获取参数的 ARN，请使用 AWS CLI 运行以下命令。将 name_of_parameter_store_secret 替换为您的 Parameter Store 密钥名称。

$ aws ssm get-parameter —name <name_of_parameter_store_secret> —with-decryption

**注意：**引用 Secrets Manager 密钥的参数不能使用 Parameter Store 版本控制或历史记录功能。有关详细信息，请参阅限制。

相关信息

检查已停止的任务是否有错误