EC2 Image Builder 故障排除 - EC2 Image Builder
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

EC2 Image Builder 故障排除

EC2 Image Builder 与集成, Amazon Web Services 用于监控和故障排除,可帮助您解决映像构建问题。Image Builder 跟踪并显示映像构建过程中每个步骤的进度。此外,Image Builder 可以将日志导出到您提供的 Amazon S3 位置。

对于高级故障排除,您可以使用 Amazon Systems Manager Run Command 运行预定义的命令和脚本。

管道构建故障排除

如果 Image Builder 管道构建失败,Image Builder 将返回一条描述此失败的错误消息。Image Builder 还会在失败消息中返回 workflow execution ID,例如下面的输出示例:

Workflow Execution ID: wf-12345abc-6789-0123-abc4-567890123abc failed with reason: …

Image Builder 通过一系列步骤来安排和指导映像构建操作,这些步骤是为其标准映像创建过程中的运行时阶段定义的。每个流程的构建和测试阶段都有一个关联的工作流程。当 Image Builder 运行工作流程来构建或测试新映像时,它会生成一个用于跟踪运行时详细信息的工作流程元数据资源。

容器映像还有一个在分发期间运行的额外工作流程。

研究工作流程运行时实例故障的详细信息

要解决工作流程的运行时故障,您可以使用调用GetWorkflowExecutionListWorkflowStepExecutionsAPI 操作workflow execution ID

查看工作流程运行时日志
  • 亚马逊 CloudWatch 日志

    Image Builder 将详细的工作流程执行日志发布到以下 Image Builder CloudWatch 日志组和直播:

    LogGroup:

    /aws/imagebuilder/ImageName

    LogStream (x.x.x/x):

    ImageVersion/ImageBuildVersion

    使用 CloudWatch Logs,您可以使用筛选模式搜索日志数据。有关更多信息,请参阅 Amazon Logs 用户指南中的使用筛选模式搜索 CloudWatch 日志数据

  • Amazon CloudTrail

    CloudTrail 如果在您的账户中激活了所有构建活动,则所有构建活动也会被登录。您可以按来源筛选 CloudTrail 事件imagebuilder.amazonaws.com。或者,您可以搜索执行日志中返回的 Amazon EC2 实例 ID,以查看有关管道执行的更多详细信息。

  • Amazon Simple Storage Service (S3)

    如果您在基础设施配置中指定了 S3 存储桶名称和键前缀,则工作流程步骤运行时日志路径将遵循以下模式:

    S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName

    您发送到 S3 存储桶的日志将显示映像生成过程中 EC2 实例上的活动的步骤和错误消息。这些日志包含了来自组件管理器的日志输出、已运行组件的定义以及在实例上执行的所有步骤的详细输出(采用 JSON 编写)。如果遇到问题,则应从 application.log 开始查看这些文件,以诊断实例上的问题原因。

默认情况下,当管道出现故障时,Image Builder 会关闭正在运行的 Amazon EC2 构建或测试实例。您可以更改管道使用的基础设施配置资源的实例设置,以保留您的构建或测试实例以进行故障排除。

要在控制台中更改实例设置,您必须清除基础设施配置资源故障排除设置部分中的失败时终止实例复选框。

您也可以在 Amazon CLI中使用 update-infrastructure-configuration 命令更改实例设置。在 JSON 文件将 terminateInstanceOnFailure 值设置为 false,该命令通过 --cli-input-json 参数引用该值。有关更多信息,请参阅 更新基础设施配置

故障排除场景

本节列出了以下详细的故障排除场景:

要查看场景的详细信息,请选择场景标题将其展开。您可以同时扩展多个标题。

描述

管道构建失败,显示 “AccessDenied:访问被拒绝” 状态代码:403"。

原因

可能的原因包括:

  • 实例配置文件没有所需的权限以访问 API 或组件资源。

  • 实例配置文件角色缺少登录 Amazon S3 所需的权限。最常见的是,当实例配置文件角色对您的 S3 存储桶没有PutObject权限时,就会发生这种情况。

解决方案

根据原因,可以按以下操作解决此问题:

  • 实例配置文件缺少托管策略 – 将缺少的策略添加到您的实例配置文件角色中。然后再次运行管道。

  • 实例配置文件缺少 S3 存储桶的写入权限 — 向您的实例配置文件角色添加授予写入您的 S3 存储桶的PutObject权限的策略。然后再次运行管道。

描述

管道构建失败,显示 “状态 = TimedOut '” 和 “失败消息 = '步骤验证目标实例上的 Systems Manager 代理可用性时步骤超时'”。

原因

可能的原因包括:

  • 启动以执行构建操作和运行组件的实例无法访问 Systems Manager 端点。

  • 实例配置文件没有所需的权限

解决方案

根据可能的原因,可以按以下操作解决此问题:

  • 访问问题,私有子网 — 如果您在私有子网中构建,请确保已为 Systems Manager、Image Builder 和 Amazon S3CloudWatch/(如果要记录)设置了PrivateLink 终端节点。有关设置 PrivateLink 终端节点的更多信息,请参阅 VPC 终端节点概念(Amazon PrivateLink)

  • 缺少权限 - 将以下托管策略添加到 Image Builder 的 IAM 服务相关角色中:

    • EC2 InstanceProfileForImageBuilder

    • EC2 InstanceProfileForImageBuilder ECR ContainerBuilds

    • 亚马逊 SSM ManagedInstanceCore

    有关 Image Builder 服务相关角色的更多信息,请参阅 使用 EC2 Image Builder 的服务相关角色

描述

当用于构建 Image Builder Windows AMI 的实例类型与用于从 AMI 启动的实例类型不匹配时,可能会出现非根卷在启动时处于离线状态的问题。这主要发生在构建实例使用的架构比启动实例更新的架构时。

以下示例演示了在 EC2 Nitro 实例类型上构建并在 EC2 Xen 实例上启动的 Image Builder AMI 时会发生什么:

构建实例类型:m5.large (Nitro)

启动实例类型:t2.medium (Xen)

PS C:\Users\Administrator> get-disk Number Friendly Name Serial Number Health Status Operational Status Total Size Partition Style ------ ------------- ------------- ------------- ------------------ ---------- --------------- 0 AWS PVDISK vol0abc12d34e567f8a9 Healthy Online 30 GB MBR 1 AWS PVDISK vol1bcd23e45f678a9b0 Healthy Offline 8 GB MBR

原因

由于 Windows 的默认设置,新发现的磁盘不会自动联机并进行格式化。在 EC2 上实例类型更改时,Windows 会将其视为发现的新磁盘。这是因为底层驱动程序发生了变化。

解决方案

我们建议您在构建要启动的 Windows AMI 时使用相同的实例类型系统。请勿在基础设施配置中包含基于不同系统构建的实例类型。如果您指定的任何实例类型使用 Nitro 系统,则它们都应使用 Nitro 系统。

有关基于 Nitro 系统构建的实例的更多信息,请参阅《适用于 Windows 实例的 Amazon EC2 用户指南》中的基于 Nitro 系统构建实例

描述

您使用的是 CIS 强化的基础映像,但构建失败。

原因

/tmp 目录被归类为 noexec 时,可能会导致 Image Builder 出现故障。

解决方案

在映像配方 workingDirectory 字段中为工作目录选择其他位置。有关更多信息,请参阅ImageRecipe数据类型说明。

描述

Systems Manager Automation 显示在 AssertInventoryCollection 自动化步骤中的一个失败。

原因

您或您的组织可能已创建一个 Systems Manager State Manager 关联,用于收集 EC2 实例的清单信息。如果您的 Image Builder 管道启用了增强型映像元数据收集(这是默认设置),Image Builder 会尝试为构建实例创建新的清单关联。但是,Systems Manager 不允许托管实例存在多个清单关联,如果已经存在一个关联,则会阻止产生新关联。这会导致操作失败,并导致管道构建失败。

解决方案

要解决此问题,请使用以下其中一种方法,关闭增强型映像元数据收集:

  • 在控制台中更新您的映像管道,以清除“启用增强型元数据收集”复选框。保存更改并运行管道构建。

    有关使用 EC2 Image Builder 控制台更新 AMI 映像管道的更多信息,请参阅 更新 AMI 映像管道(控制台)。有关使用 EC2 Image Builder 控制台更新容器映像管道的更多信息,请参阅 更新容器映像管道(控制台)

  • 您也可以在 Amazon CLI中使用 update-image-pipeline 命令更新映像管道。为此,请在您的 JSON 文件中包含 EnhancedImageMetadataEnabled 属性,将其设置为 false。以下示例显示属性设置为 false

    { "name": "MyWindows2019Pipeline", "description": "Builds Windows 2019 Images", "enhancedImageMetadataEnabled": false, "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 60 }, "schedule": { "scheduleExpression": "cron(0 0 * * SUN *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "ENABLED" }

为防止新管道发生这种情况,请在使用 EC2 Image Builder 控制台创建新管道时,清除“启用增强型元数据收集”复选框,或者在使用 Amazon CLI创建管道时,false 在 JSON 文件中设置 EnhancedImageMetadataEnabled 属性的值。