本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Image Builder 问题疑难解答 EC2 Image Builder 与集成， AWS 服务 用于监控和故障排除，可帮助您解决映像构建问题。Image Builder 跟踪并显示映像构建过程中每个步骤的进度。此外，Image Builder 可以将日志导出到您提供的 Amazon S3 位置。 对于高级故障排除，您可以使用 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) 运行预定义的命令和脚本。 **Topics** + [管道构建故障排除](#troubleshooting-pipelines) + [故障排除场景](#image-builder-troubleshooting-scenarios) ## 管道构建故障排除 如果 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 运行工作流程来构建或测试新映像时，它会生成一个用于跟踪运行时详细信息的工作流程元数据资源。 容器映像还有一个在分发期间运行的额外工作流程。 **研究工作流程运行时实例故障的详细信息** 要解决工作流程的运行时故障，您可以使用调用[GetWorkflowExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowExecution.html)和 [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowExecution.html)API 操作`workflow execution ID`。 **查看工作流程运行时日志** + **亚马逊 CloudWatch 日志** Image Builder 将详细的工作流程执行日志发布到以下 Image Builder CloudWatch 日志组和直播： 使用 CloudWatch Logs，您可以使用筛选模式搜索日志数据。有关更多信息，请参阅 *Amazon Logs 用户指南中的使用筛选模式搜索 CloudWatch 日志*[数据](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SearchDataFilterPattern.html)。 + **AWS 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 构建或测试实例。您可以更改管道使用的基础设施配置资源的实例设置，以保留您的构建或测试实例以进行故障排除。 要在控制台中更改实例设置，您必须清除基础设施配置资源**故障排除设置**部分中的**失败时终止实例**复选框。 您也可以在 AWS CLI中使用 **update-infrastructure-configuration** 命令更改实例设置。在 JSON 文件将 `terminateInstanceOnFailure` 值设置为 `false`，该命令通过 `--cli-input-json` 参数引用该值。有关更多信息，请参阅 [更新基础设施配置](update-infra-config.md)。 ## 故障排除场景 本节列出了以下详细的故障排除场景： + [访问被拒绝 - 状态码 403](#ts-access-denied) + [验证构建实例上的 Systems Manager 代理可用性时构建超时](#ts-timeout-ssm-agent) + [Windows 辅助磁盘在启动时处于离线状态](#ts-win-disk-offline) + [使用 CIS 强化的基础映像构建失败](#ts-cis-base) + [AssertInventoryCollection 失败（Systems Manager 自动化）](#ts-ssm-mult-inventory) 要查看场景的详细信息，请选择场景标题将其展开。您可以同时扩展多个标题。 ### 访问被拒绝 - 状态码 403 #### 说明 管道构建失败，显示 “AccessDenied：访问被拒绝” 状态代码：403"。 #### 原因 可能的原因包括： + 实例配置文件没有访问APIs 或组件资源所需的[权限](set-up-ib-env.md#image-builder-IAM-prereq)。 + 实例配置文件角色缺少登录 Amazon S3 所需的权限。最常见的是，当实例配置文件角色对您的 S3 存储桶没有**PutObject**权限时，就会发生这种情况。 #### 解决方案 根据原因，可以按以下操作解决此问题： + **实例配置文件缺少托管策略** – 将缺少的策略添加到您的实例配置文件角色中。然后再次运行管道。 + **实例配置文件缺少 S3 存储桶的写入权限** — 向您的实例配置文件角色添加授予写入您的 S3 存储桶的**PutObject**权限的策略。然后再次运行管道。 ### 验证构建实例上的 Systems Manager 代理可用性时构建超时 #### 说明 管道构建失败，显示 “状态 = TimedOut '” 和 “失败消息 = '步骤验证目标实例上的 Systems Manager 代理可用性时步骤超时'”。 #### 原因 可能的原因包括： + 启动以执行构建操作和运行组件的实例无法访问 Systems Manager 端点。 + 实例配置文件没有所需的[权限](set-up-ib-env.md#image-builder-IAM-prereq)。 #### 解决方案 根据可能的原因，可以按以下操作解决此问题： + **访问问题，私有子网** — 如果您在私有子网中构建，请确保已为 Systems Manager、Image Builder 和 Amazon S3CloudWatch/（如果要记录）设置了PrivateLink 终端节点。有关设置 PrivateLink 终端节点的更多信息，请参阅[通过访问 AWS 服务 AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-aws-services.html)。 + **缺少权限** - 将以下托管策略添加到 Image Builder 的 IAM 服务相关角色中： + EC2InstanceProfileForImageBuilder + EC2InstanceProfileForImageBuilderECRContainer构建 + 亚马逊 SSMManaged InstanceCore 有关 Image Builder 服务相关角色的更多信息，请参阅 [使用 Image Builder 的 IAM 服务相关角色](image-builder-service-linked-role.md)。 ### Windows 辅助磁盘在启动时处于离线状态 #### 说明 当用于构建 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 系统构建的实例的更多信息，请参阅**《Amazon EC2 用户指南》中的[基于 Nitro 系统构建实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#ec2-nitro-instances)。 ### 使用 CIS 强化的基础映像构建失败 #### 说明 您使用的是 CIS 强化的基础映像，但构建失败。 #### 原因 当 `/tmp` 目录被归类为 `noexec` 时，可能会导致 Image Builder 出现故障。 #### 解决方案 在映像配方 `workingDirectory` 字段中为工作目录选择其他位置。有关更多信息，请参阅[ImageRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageRecipe.html)数据类型说明。 ### AssertInventoryCollection 失败（Systems Manager 自动化） #### 说明 Systems Manager Automation 显示在 `AssertInventoryCollection` 自动化步骤中的一个失败。 #### 原因 您或您的组织可能已创建一个 Systems Manager State Manager 关联，用于收集 EC2 实例的清单信息。如果您的 Image Builder 管道启用了增强型映像元数据收集（这是默认设置），Image Builder 会尝试为构建实例创建新的清单关联。但是，Systems Manager 不允许托管实例存在多个清单关联，如果已经存在一个关联，则会阻止产生新关联。这会导致操作失败，并导致管道构建失败。 #### 解决方案 要解决此问题，请使用以下其中一种方法，关闭增强型映像元数据收集： + 在控制台中更新您的映像管道，以清除“**启用增强型元数据收集**”复选框。保存更改并运行管道构建。 有关使用 EC2 Image Builder 控制台更新 AMI 映像管道的更多信息，请参阅 [通过控制台更新 AMI 映像管道](update-image-pipeline-console.md)。有关使用 EC2 Image Builder 控制台更新容器映像管道的更多信息，请参阅 [通过控制台更新容器映像管道](update-container-pipeline-console.md)。 + 您也可以在 AWS 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 控制台创建新管道时，清除“**启用增强型元数据收集**”复选框，或者在使用 AWS CLI创建管道时，`false` 在 JSON 文件中设置 `EnhancedImageMetadataEnabled` 属性的值。