如何排查 EC2 Image Builder 中的编译管道超时错误？

3 分钟阅读

我想排查 EC2 Image Builder 中的编译管道超时错误。

简短描述

以下是 Image Builder 构建管道在 LaunchBuildInstance、BootstrapBuildInstance 或 ApplyBuildComponent 工作流程步骤中失败并伴随步骤超时错误的常见原因：

构建实例无法连接到 AWS Systems Manager。
AWS Identity and Access Management (IAM) 角色的权限不正确。
私有子网无法访问互联网。
存在重复的根设备名称。

解决方法

要排查构建管道超时错误，请参阅以下场景。

**注意：**如果在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

在构建实例上验证 SSM 代理的可用性时，发生超时

如果构建过程在构建实例上验证 AWS Systems Manager 代理时发生构建管道超时，则您可能会收到以下错误：

“Workflow Execution ID: failed with reason: ExpectationNotMet. ssm:*CommandInvocations returned terminal state Failed in workflow step LaunchBuildInstance.”（工作流程执行 ID：失败，原因是：ExpectationNotMet. ssm:*CommandInvocations 在工作流程步骤 LaunchBuildInstance 中返回的终端状态为“失败”。）

“Workflow Execution ID: failed with reason: An error occurred (InvalidInstanceId) when calling the SendCommand operation: Instances [[i-1a1b1c1d1e1f1g1h1]] not in a valid state for account in workflow step LaunchBuildInstance.”（工作流程执行 ID：失败，原因是：调用 SendCommand 操作时出现错误（InvalidInstanceId）：在工作流程步骤 LaunchBuildInstance 中，实例 [[i-1a1b1c1d1e1f1g1h1]] 处于无效状态。）

“Workflow Execution ID: failed with reason: ExpectationNotMet. ec2:DescribeInstanceStatus did not meet terminal states: [['passed']] after 100 attempts.Reason: Timeout. in workflow step LaunchBuildInstance.”（工作流程执行 ID：失败，原因是：ExpectationNotMet. ec2:DescribeInstanceStatus 在工作流程步骤 launchBuildInstance 中尝试 100 次后未达到终端状态：[['passed']]。原因：超时。）

当实例没有管道基础设施角色所需的 IAM 权限时，就会发生这些构建管道超时错误。当 SSM 代理可以连接到端点时，也可能会发生这些错误。

实例没有所需的 IAM 权限

如果您的构建实例没有所需的 IAM 权限，请将 AmazonSSMManagedInstanceCore托管式策略添加到您的 IAM 角色中。您的 IAM 角色是在 Image Builder 基础设施配置中指定的。此外，请确保允许 AWSServiceRoleForImageBuilder 角色使用 AWS Key Management Service (AWS KMS) 密钥。此角色需要访问配置映像配方块设备时指定的 AWS KMS 密钥。有关更多信息，请参阅允许密钥用户使用 KMS 密钥。

SSM 代理无法连接到端点

如果 SSM 代理无法连接到端点，则采取以下操作：

如果您使用互联网网关，并在公有子网内进行构建，则将子网配置为自动分配公有 IPv4 地址。
如果您是在使用 NAT 的私有子网内进行构建，则将 NAT 配置为使用公有子网。
如果您是在使用 Amazon Virtual Private Cloud (Amazon VPC) 端点的私有子网内进行构建，则为 Systems Manager 设置 AWS PrivateLink 端点。有关详细信息，请参阅如何创建 VPC 端点，才能在不连接互联网的情况下使用 Systems Manager 管理私有 EC2 实例？
请确保安全组和网络访问控制列表（网络 ACL）允许临时端口 (1024–65535) 的入站连接。它们还必须允许 443 端口上的出站连接。对于配置 PrivateLink 端点的私有子网，连接到 Amazon VPC 端点的安全组必须允许 443 端口上的入站连接。必须允许这些来自子网或 Amazon VPC CIDR 地址的入站连接。

当构建下载 AWS CLI 时，发生超时

当您在私有子网上进行构建且拥有 aws-cli-version-2-linux 或 aws-cli-version-2-windows 组件时，可能会在 ApplyBuildComponents 步骤中发生构建超时。

对于容器构建，可能会在 BootstrapBuildInstance 步骤中发生构建超时。当实例的 AMI 上不存在 AWS CLI 且引导脚本尝试通过互联网安装 AWS CLI 时，就会发生超时。

要解决此超时，请执行以下操作：

允许子网通过 NAT 网关或互联网网关进行互联网连接。
使用安装了 AWS CLI 的自定义 AMI。

当根设备名称重复时，发生超时

当您使用 CreateImageRecipe API 创建配方时，如果您将根设备命名为 /dev/xvda 或 /dev/sda1，可能会出现错误。为防止构建实例中出现重复的根设备名称，请检查源 AMI 中的根设备映射。如果存在重复的根设备名称，则会发生超时并出现以下错误：

**注意：**当您在 AWS 管理控制台中使用映像配方时，无法创建重复的设备名称。此外，AWS Nitro System 实例类型（或 Xen 实例类型）是仅有的不会因为设备名称重复而失败的实例类型。

对于 AMI 中的根设备，请运行 describe-images 命令以确认源 AMI 的设备名称。使用与映像配方中相同的设备名称。

当构建获取 Image Builder 组件时，发生超时

如果您在私有子网上进行构建，并且在下载组件时 Image Builder 失败，则会出现以下错误：

“failed with reason: failed to download the EC2 Image Builder Component, operation error imagebuilder: GetComponent, exceeded maximum number of attempts, 3, dial tcp i/o timeout.”（失败，原因是：无法下载 EC2 Image Builder 组件，操作错误 imagebuilder：GetComponent，超过最大尝试次数，3，拨号 tcp 输入/输出超时。）

要解决上述错误，请检查配置。或者，如果您没有为 Image Builder 基础设施配置中使用的 VPC 和子网配置接口 Amazon VPC 端点，则创建接口 Amazon VPC 端点。

构建检索映像列表时发生超时

如果您使用基于 Amazon Linux 的 AMI 在私有子网上进行构建，则可能会出现以下超时错误：

“Could not retrieve mirrorlist; error was 12: Timeout was reached.”（无法检索映像列表；错误是 12：已达到超时。）

Amazon Linux 映像列表存储在 Amazon Simple Storage Service (Amazon S3) 上。请确认 Amazon S3 的 Amazon VPC 网关端点存在。或者，创建 Amazon VPC 网关端点。当您创建端点时，Amazon S3 前缀列表会自动添加到路由表中。但是，依照最佳实践，请确认已添加了前缀列表。

如果您在非 Amazon Linux AMI 上进行构建，则映像列表不会存储在 Amazon S3 上。此外，当构建获取存储库/映像列表时，可能会发生构建超时。请确保您的网络防火墙或代理允许放行存储库地址或 URL。如果存储库/映像列表需要连接互联网，则允许子网通过 NAT 网关连接互联网。

在 ApplyBuildComponents 步骤中发生超时

如果在 ApplyBuildComponents 步骤中发生构建超时，则会出现以下错误：

“Workflow Execution ID: failed with reason: ExpectationNotMet. ssm:ListCommandInvocations did not meet terminal states: [['Success']] after 1440 attempts.Reason: Timeout. in workflow step ApplyBuildComponents.”（工作流程执行 ID：失败，原因是：ExpectationNotMet. ssm:ListCommandInvocations 在工作流程步骤 ApplyBuildComponents 中尝试 1440 次后未达到终端状态：[['Success']] 。原因：超时。）

要对此错误进行故障排除，请采取以下措施：

分析发送到基础设施的 Amazon S3 存储桶的日志。有关更多信息，请参阅管道构建故障排除的审查工作流程运行时日志部分中的 Amazon Simple Storage Service (Amazon S3) 要点。
分析您用来构建或测试新映像的 Amazon Elastic Compute Cloud (Amazon EC2) 实例上的组件日志。在检查日志之前，请在基础设施配置的故障排除会话中关闭故障时终止实例功能。
**注意：**detailedoutput.json 日志文件描述了组件失败或超时的原因。application.log 文件提供调试级别的故障排除信息。
检查您的文档的 YAML 架构中指定的 timeoutSeconds参数值。默认值为 7200。根据需要，更新组件中每个步骤的此值。值 -1 表示无穷大。