如何对 EC2 Image Builder 的管道故障进行故障排除？

2 分钟阅读

我想对 EC2 Image Builder 的管道故障进行故障排除。

简短描述

如果您的 Image Builder 管道出现故障，则会出现一条错误消息，其中会返回工作流程执行 ID，并描述您的管道故障的原因：

“工作流程执行 ID：示例工作流程 ID 失败，原因：示例原因”

流程的每个构建和测试阶段都有一个相关的工作流程。容器映像还有一个额外的工作流程，在分发期间运行。此外，每个工作流程都包含了构建黄金亚马逊机器映像所需的步骤。

解决方法

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

要排查 Image Builder 管道故障，请完成以下步骤：

检查导致管道故障的工作流程阶段和步骤

要检查导致管道故障的工作流程阶段和步骤，请使用以下方法之一：

使用 API
要检查导致管道故障的工作流阶段和步骤，请针对您的工作流程执行 ID 使用 GetWorkflowExecution 和ListWorkflowStepExecution API 命令。

使用 AWS 管理控制台
要使用 AWS 管理控制台检查导致管道故障的工作流程阶段和步骤，请完成以下步骤：

打开 Image Builder 控制台。
在左侧窗格中，选择 Image Pipelines（映像管道）。然后，选择您的管道。
在 Output Images（输出映像）下，选择发生故障的 Output Image Version（输出映像版本）。
在 Workflow（工作流程）下，选择工作流程下拉列表，然后选择发生故障的 stage（阶段）。故障阶段的步骤列表将会显示。

当您确定导致管道故障的工作流程阶段和步骤时，请使用以下方法进一步故障排除。

检查发送到 CloudWatch Logs 的日志

Image Builder 向 /aws/imagebuilder/ImageName 日志组和 ImageVersion/ImageBuildVersion 日志流发布了详细的工作流程日志。您可以从 Amazon CloudWatch 控制台或 Image Builder 控制台查看这些日志流。

要检查从 Image Builder 控制台发送到 CloudWatch Logs 的日志，请完成以下步骤：

打开 Image Builder 控制台。
在左侧窗格中，选择 Image Pipelines（映像管道）。然后，选择您的管道。
在 Output Images（输出映像）下，选择发生故障的 Output Image Version（输出映像版本）。
在 Workflow（工作流程）下，选择工作流程下拉列表，然后选择发生故障的 stage（阶段）。
选择发生故障的步骤的步骤 ID。
选择 Application logs（应用程序日志）。
查看 Application logs（应用程序日志）以进一步故障排除。

**注意：**如果在完成上述步骤后仍无法对问题进行故障排除，请继续使用后续方法。

检查发送到 Amazon S3 的日志

Amazon Simple Storage Service (Amazon S3) 日志显示了构建过程中 Amazon Elastic Compute Cloud (Amazon EC2) 实例活动的步骤和错误。Amazon S3 日志包括来自组件管理器的日志输出、组件定义。这些日志提供了在 Amazon EC2 实例上采取的步骤的详细 JSON 输出。

如果您在基础设施配置中指定了 Amazon S3 存储桶名称和键前缀，则可以在 S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName 中找到工作流程步骤日志路径

如果您没有指定 Amazon S3 存储桶名称和键前缀，请打开 Image Builder 控制台并导航到 Troubleshooting settings（故障排除设置）。然后，在 Logs（日志）下，指定 Image Builder 可以将日志写入的 Amazon S3 存储桶。指定 Amazon S3 存储桶后，再次运行管道以收集日志并将日志存储到存储桶中。

检查 Amazon EC2 实例日志

AWS Task Orchestrator 和 Executor 组件管理器 (AWSTOE) 会在用于构建和测试新映像的实例上创建日志文件夹。每当您的组件运行时，就会创建这些日志文件夹。对于容器映像，日志文件夹存储在容器中。

**注意：**默认情况下，当管道构建失败时，Image Builder 会关闭构建实例或测试实例。要保留您的构建实例或测试实例以进行故障排除，请修改管道的基础设施配置资源的实例设置。要修改实例设置，请打开 Image Builder 控制台，并导航到基础设施配置资源的 Troubleshooting settings（故障排除设置）。然后，停用 Terminate instance on failure（故障时终止实例）选项。

此外，您还可以使用 update-infrastructure-configuration 命令来修改实例设置。请确保将 TerminateInstanceOnFailure 值设置为 false。有关更多信息，请参阅更新基础设施配置。

连接到构建实例或测试实例，在以下位置找到运行时日志：

对于 Linux，检查 /var/lib/amazon/toe/file_prefix_runtime_executionID 目录。
对于 Windows，检查 env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\file_prefix_run time_executionID 目录。

示例日志文件：/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

在前面的日志目录中，检查以下文件以进一步对管道故障进行故障排除：

application.log - 包括来自 AWSTOE 的带有时间戳的调试级别信息，这些信息与组件运行时发生的活动有关。
detailedoutput.json - 包括有关组件运行时应用于该组件的所有文档、阶段和步骤的运行状态、输入、输出和故障的详细信息。
console.log - 包括 AWSTOE 在组件运行时写入到控制台的标准输出 (stdout) 和标准错误 (stderr) 信息。
chaining.json - 表示 AWSTOE 应用于解析链接表达式的优化。

查看 CloudTrail 事件

如果在您的账户中激活了 AWS CloudTrail，则会记录所有构建活动。要筛选 CloudTrail 事件，请按 source: imagebuilder.amazonaws.com 进行筛选，按 username: Image Builder 进行筛选，或搜索关联的 Amazon EC2 实例 ID。这些筛选器会返回日志，显示有关您的管道的更多详细信息。

要在分发过程中对 API 跟踪记录进行故障排除，请按 username: Ec2ImageBuilderIntegrationService 筛选 CloudTrail 事件，用于在Distribution（分发）过程中对 API 跟踪记录进行故障排除。使用此方法来检索与 Image Builder 调用失败的 API 相关的信息。