Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用失败上下文查找映像构建失败的原因

当映像构建失败时，Image Builder 会报告映像中的失败state。状态携带一条描述失败的消息reason，以及其中的结构化故障上下文failureContext。

失败上下文是一组字段，用于命名失败中涉及的工作流、工作流步骤、组件步骤和目标区域。由于这些字段是结构化的，因此您的自动化可以直接对它们进行分支，并且您可以将它们的值传递给其他 Image Builder API 操作以获取更多细节。

Image Builder 返回GetImageListImageBuildVersions、和 ListImagePipelineImagesAPI 操作的失败上下文，并将其显示在图像生成器中 Amazon Web Services 管理控制台。

失败上下文包含什么

失败上下文描述了三个级别的故障。每个成员都是可选的，Image Builder 仅返回适用于失败的成员。有关成员、其类型和限制，请参阅ImageState《EC2 Image Builder API 参考》。

中的示例查看失败图像的失败上下文显示了 Image Builder 在组件故障和分发失败时返回的成员。

查看失败图像的失败上下文

在 Image Builder 控制台中查看故障上下文

无论图像状态如何，Image Builder 都会显示Failed图像的故障详情。

使用获取失败上下文 Amazon 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]"

追踪故障的根本原因

失败上下文将失败范围缩小到一个步骤。使用以下步骤从该步骤转到解释该步骤的证据。

从日志中获取完整的组件输出

失败上下文报告组件步骤引发的错误，但不报告该步骤运行的脚本的标准输出和标准错误。Image Builder 将该输出保留在组件日志中。

当组件出现故障时， EC2 TOE 会将第一个失败步骤的详细信息写入控制台日志，然后将该步骤的完整标准错误输出写入控制台日志。

  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单独无法识别哪个组件失败。

EC2 TOE Stderr仅当失败的步骤生成它们时才会写入ErrorMessage。

构建完成后，Image Builder 会将组件 CloudWatch 日志流式传输到 Amazon Logs。如果您在基础设施配置中指定了 Amazon S3 存储桶，Image Builder 也会将其写入其中。有关日志组和直播名称，请参阅使用 Amazon 日志监控 Image Builder CloudWatch 日志。有关 EC2 TOE 生成的文件以及每个文件包含的内容，请参见组件日志。

在 AI 代理中使用故障上下文

失败上下文旨在供自动化和人员读取。对失败的构建进行故障排除的 AI 代理会读取命名字段，并将其值用作下一次 API 调用的参数。这使得诊断可以重复，并且可以防止代理猜测哪个组件或进行调查。

您可以通过以下任一方式使用失败上下文：

如果您在失败上下文中构建自己的自动化，请将每个成员视为可选成员，并检查您使用的成员而不是其failureContext自身的存在。Image Builder 返回哪些成员取决于失败情况，Image Builder 可以随着时间的推移添加成员。

注意事项

使用失败上下文时，请注意以下几点：