本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用失败上下文查找映像构建失败的原因
当映像构建失败时，Image Builder 会报告映像中的失败`state`。状态携带一条描述失败的消息`reason`，以及其中的结构化**故障上下文**`failureContext`。
失败上下文是一组字段，用于命名失败中涉及的工作流、工作流步骤、组件步骤和目标区域。由于这些字段是结构化的，因此您的自动化可以直接对它们进行分支，并且您可以将它们的值传递给其他 Image Builder API 操作以获取更多细节。
Image Builder 返回[GetImage[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html)、和 [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)API 操作的失败上下文，并将其显示在图像生成器中 AWS 管理控制台。
**Topics**
+ [失败上下文包含什么](#image-failure-context-fields)
+ [查看失败图像的失败上下文](#image-failure-context-view)
+ [追踪故障的根本原因](#image-failure-context-rca)
+ [在 AI 代理中使用故障上下文](#image-failure-context-ai)
+ [注意事项](#image-failure-context-considerations)
## 失败上下文包含什么
失败上下文描述了三个级别的故障。每个成员都是可选的，Image Builder 仅返回适用于失败的成员。有关成员、其类型和限制，请参阅[ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)《*EC2 Image Builder API 参考*》。
这张图片
图像失败时处于哪个阶段，以及正在运行哪个工作流程和工作流程步骤。工作流程和步骤执行标识符与 and take 的[ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)值相同，因此您可以将它们直接传递给这些操作。[GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)
组件步骤
对于组件导致的生成或测试失败、运行的组件、其文档中的阶段和步骤、该步骤运行的 AWSTOE 操作模块以及该步骤报告的错误。Image Builder 按版本标识组件，因此即使您的配方引用了通配符版本，它也会命名运行的确切修订版。有关操作模块，请参见[支持的操作模块 AWSTOE 组件管理器](toe-action-modules.md)。
目的地地区
对于分发或集成失败，则为整个分布的摘要错误，失败的每个目标都有一个条目。每个条目都包含其分发的结束方式、Image Builder 调用的服务的错误，对于跨账户分发，还有 Image Builder 分发到的目标 AWS 账户 。当 AMI 复制成功但之后的步骤没有成功时，该条目还会命名该步骤：关联许可证配置、更新启动模板、放置 SSM 参数、更新 Amazon EC2 快速启动配置或导出 AMI。省略成功的目的地。
**注意**
Image Builder 返回哪些成员取决于构建的进展情况。在 Image Builder 启动工作流程之前发生的故障没有工作流程可命名。例如，如果配方中的父图像已不存在，则失败上下文会标识阶段，仅此而已。
中的示例[查看失败图像的失败上下文](#image-failure-context-view)显示了 Image Builder 在组件故障和分发失败时返回的成员。
## 查看失败图像的失败上下文
**在 Image Builder 控制台中查看故障上下文**
无论图像状态如何，Image Builder 都会显示`Failed`图像的故障详情。
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中选择 Imag **es**，然后选择失败的映像构建版本。您也可以打开管道的**输出图像**列表。
1. 选择`Failed`图像状态。Image Builder 显示图像的失败详情，并将失败的工作流程步骤链接到其运行时详细信息。
**使用获取失败上下文 AWS CLI**
使用失败映像的编译版本 ARN 运行**get-image**命令。
```
aws imagebuilder get-image \
--image-build-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0/1 \
--query "image.state"
```
以下示例输出显示了由于组件步骤运行的脚本以非零状态退出的脚本而失败的构建。
```
{
"status": "FAILED",
"reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
"failureContext": {
"imageStatus": "BUILDING",
"workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/{{x.x.x/x}}",
"stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"failedStep": "ApplyBuildComponents",
"componentFailure": {
"componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
"phaseName": "build",
"stepName": "InstallPackages",
"action": "ExecuteBash",
"errorMessage": "exit status 1"
}
}
}
```
下一个示例输出显示了一张成功构建和测试但失败的镜像，而 Image Builder 更新了三个目标区域的启动模板。所有其他目的地的构建都成功了，因此只显示了三个失败的区域。
```
{
"status": "FAILED",
"reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
"failureContext": {
"imageStatus": "INTEGRATING",
"distributionFailure": {
"errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
"regionFailures": [
{
"region": "eu-west-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
},
{
"region": "us-east-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
},
{
"region": "us-east-2",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
}
]
}
}
}
```
要在不检查每个版本的情况下在账户中查找失败的构建，请列出映像版本并筛选映像状态。以下示例返回图像的失败构建，以及每个映像的失败上下文。
```
aws imagebuilder list-image-build-versions \
--image-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0 \
--query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"
```
## 追踪故障的根本原因
失败上下文将失败范围缩小到一个步骤。使用以下步骤从该步骤转到解释该步骤的证据。
1. **阅读`imageStatus`以找到失败的阶段。**值为`BUILDING`或`TESTING`表示故障发生在 Image Builder 启动的 Amazon EC2 实例上，因此组件日志是下一个要查看的地方。值为`DISTRIBUTING`或`INTEGRATING`表示映像已构建，但故障出在您的分发设置或目标账户中或。
1. **阅读描述具体故障的成员。**`componentFailure`如果存在，它将标识组件文档中失败的步骤，以及该步骤运行的操作和报告的错误。如果存在，`distributionFailure`则中的每个条目都会`regionFailures`为您提供目的地及其自身的错误。
1. **检查工作流程运行时详细信息。**致电[ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)`workflowExecutionId`查看工作流程中的每个步骤以及失败步骤在序列中的位置。调[GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)用`stepExecutionId`以获取失败步骤本身的输入、输出和回滚状态。
以下示例列出了执行失败的工作流程的步骤。
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **阅读失败步骤的日志。**使用`workflowExecutionId`和直接转`failedStep`到该步骤的日志路径。有关更多信息，请参阅 [从日志中获取完整的组件输出](#image-failure-context-logs)。
1. **如果需要，可以重现故障。**要保持构建实例的运行以便您可以连接到它，请在管道使用的基础设施配置中清除 “**失败时终止实例**” 设置。有关更多信息，请参阅 [管道构建故障排除](troubleshooting.md#troubleshooting-pipelines)。
### 从日志中获取完整的组件输出
失败上下文报告组件步骤引发的错误，但不报告该步骤运行的脚本的标准输出和标准错误。Image Builder 将该输出保留在组件日志中。
当组件出现故障时， AWSTOE 会将第一个失败步骤的详细信息写入控制台日志，然后将该步骤的完整标准错误输出写入控制台日志。
```
Document: MyExampleDocument
ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
Phase: build
Step: InstallPackages
Action: ExecuteBash
ErrorMessage: exit status 1
Stderr: {{the full standard error output of the step}}
```
`ComponentArn`与`componentFailure.componentArn`报告的值相同，因此使用它来将日志块与图像的失败上下文进行匹配。 `Document`是`name`组件文档声明的，作者独立于组件资源进行选择，因此两者可能有所不同，`Document`单独无法识别哪个组件失败。
AWSTOE `Stderr`仅当失败的步骤生成它们时才会写入`ErrorMessage`。
构建完成后，Image Builder 会将组件 CloudWatch 日志流式传输到 Amazon Logs。如果您在基础设施配置中指定了 Amazon S3 存储桶，Image Builder 也会将其写入其中。有关日志组和直播名称，请参阅[使用 Amazon 日志监控 Image Builder CloudWatch 日志](monitor-cwlogs.md)。有关 AWSTOE 生成的文件以及每个文件包含的内容，请参见[组件日志](toe-use-documents.md#component-logging)。
## 在 AI 代理中使用故障上下文
失败上下文旨在供自动化和人员读取。对失败的构建进行故障排除的 AI 代理会读取命名字段，并将其值用作下一次 API 调用的参数。这使得诊断可以重复，并且可以防止代理猜测哪个组件或进行调查。
您可以通过以下任一方式使用失败上下文：
+ **在 Image Builder** 中进行故障排除 AWS 管理控制台— 由 AWS DevOps Agent 提供支持的故障排除功能使用故障上下文将其调查范围限定为在检查日志和相关资源之前失败的工作流程步骤和组件。有关更多信息，请参阅 [使用 AI 对失败的构建进行故障排除-预览](devops-agent-troubleshooting.md)。
+ **你自己的 AI 编码代**理 — 调用的代理会在响应中`GetImage`接收故障上下文，并且可以用同样的方式跟踪它。为了让您的代理更广泛地了解 Image Builder，他们需要根据发现的内容采取行动，请参阅[使用 AI 编码代理对版本进行故障排除](agent-toolkit-skill.md)。
如果您在失败上下文中构建自己的自动化，请将每个成员视为可选成员，并检查您使用的成员而不是其`failureContext`自身的存在。Image Builder 返回哪些成员取决于失败情况，Image Builder 可以随着时间的推移添加成员。
## 注意事项
使用失败上下文时，请注意以下几点：
+ Image Builder 仅为失败的图像返回失败上下文。成功的图片和您取消的图片都没有。
+ 失败的图像同时带有`reason`和`failureContext`。`reason`用于获取故障的可读摘要，并`failureContext`用于定位故障。
+ 如果组件使用该`ExecuteDocument`操作来运行嵌套文档，则故障上下文会标识 Image Builder 从您的配方中运行的组件，而不是嵌套文档。
+ 失败上下文中的错误消息有长度限制，可以被截断。组件日志包含完整的输出。
+ 失败上下文报告失败的第一步。如果有多个步骤失败，请查看工作流程步骤的执行和其余步骤的组件日志。
+ 错误消息可以包含组件或其他 AWS 服务生成的文本。如果您渲染它们或将它们传递给其他系统，请将其视为不可信的输入。