View a markdown version of this page

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

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

使用增强的 AMI 分发功能

Image Builder 为您提供高级分发功能,可将分发与构建过程分开。您可以分发已构建的映像,在不重建的情况下重试在测试或分发阶段失败的 AMI 映像,并使用自定义工作流程定义多阶段分发流程。

分发现有图像

这个 DistributeImage 操作会分发映像生成器(或您)已经创建的映像,而无需重新运行构建和测试阶段。Image Builder 使用 ARN 引用的分发配置中的目标和设置,仅运行分发阶段。

您可以通过以下三种方式之一识别源图像:

  • AMI ID — 标准 AMI 标识符,例如 ami-0abcdef1234567890。AMI 必须存在且可在您调用操作的地区访问。

  • SSM 参数 — 表单中的系统管理器参数存储参考信息 ssm:/path/to/parameter,其后的文字 ssm: 是参数名称或 ARN。该参数必须是 String 参数,其值是有效的 AMI ID。

  • 映像生成器映像版本 ARN — 您调用操作的区域中映像生成器映像的 ARN。图像的输出资源必须包含该地区的 AMI。您可以指定以内部版本号结尾的编译版本 ARN,例如 image/my-image/1.0.0/1,或者没有内部版本号的版本 ARN,例如 image/my-image/1.0.0。Image Builder 将版本 ARN 解析为其最新版本 AVAILABLE 州。

注意

源图像必须是 AMI ID、SSM 参数或映像生成器映像 ARN,并且映像生成器不接受 Amazon 商城产品代码。分发配置必须位于您调用的同一区域 DistributeImage。您无法将内联分发设置传递给此操作。

先决条件

与管道建设不同, DistributeImage 在调用时扮演执行角色。确保以下内容准备就绪:

  • 映像生成器执行角色,映像生成器可以代入该角色来执行分发。我们建议您使用创建自定义角色 EC2ImageBuilderExecutionPolicy Amazon 已附加管理策略。该政策允许 ec2:ModifyImageAttribute, ec2:ModifySnapshotAttribute,以及 ec2:EnableFastLaunch 仅在带有标签的资源上 CreatedBy: EC2 Image Builder,并允许 ssm:PutParameter 仅在以下参数上 /imagebuilder/。如果您的分配适用于其他资源,请为该角色添加所需的权限。要在没有启动模板的情况下配置 EC2 快速启动,还要附上 EC2FastLaunchFullAccess 政策。要使用启动模板配置 EC2 快速启动,启动模板必须具有 CreatedBy: EC2 Image Builder 标签。Image Builder 仅将此标签添加到发布配置更新的启动模板中 launchTemplateConfigurations。对于任何其他启动模板,请自己添加标签或附上 EC2FastLaunchFullAccess 政策。

  • 允许拨打电话 imagebuilder:DistributeImage, imagebuilder:GetDistributionConfiguration,以及 iam:PassRole 用于执行角色。Image Builder 还描述了源 AMI 以及您的证书以对其进行验证,因此您需要 ec2:DescribeImages 适用于每种来源类型。如果源是 SSM 参数,则还需要 ssm:GetParameter 对于那个参数。如果来源是映像生成器镜像 ARN,则还需要 imagebuilder:GetImage 在那张照片上。如果您在请求中包含标签,则还需要 imagebuilder:TagResource。

  • 如果分发配置将 AMI 复制到其他账户 (targetAccountIds),或者更新其他账户中的启动模板或 SSM 参数, EC2ImageBuilderDistributionCrossAccountRole 在每个账户中, Ec2ImageBuilderCrossAccountDistributionAccess policy 已附加管理策略。托管策略不涵盖启动模板或 SSM 参数。要更新它们,还要添加以下策略 使用 Image Builder 设置跨账户 AMI 分配 的清单 launchTemplateConfigurations 和参数存储参数。

Amazon Web Services 管理控制台

要在映像生成器控制台中分发现有映像,请执行以下步骤:

  1. 打开 EC2 映像生成器控制台,网址为 https://console.aws.amazon.com/imagebuilder/。

  2. 从导航窗格中,选择分配设置。

  3. 选择定义目标的分发配置,然后选择 分发图片 来自 行动 菜单。一次只能为该操作选择一个分发配置。

  4. 在 待分发的图片 部分,选择源图像类型 — AMI ID, SSM 参数,或 映像生成器映像 ARN — 并指定要分发的图像。

  5. 选择映像生成器用于执行分配的 IAM 角色。

  6. 选择 分发图片。

Amazon CLI

以下示例显示如何使用分发现有图像 分发图像 命令。你可以指定 --execution-role 按角色名或完整的 ARN;以下示例显示了这两种形式。

通过 AMI ID 进行分发

aws imagebuilder distribute-image \ --source-image ami-0abcdef1234567890 \ --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \ --execution-role arn:aws:iam::123456789012:role/MyImageBuilderDistributionRole
通过 SSM 参数进行分发

aws imagebuilder distribute-image \ --source-image ssm:/golden/latest-ami \ --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \ --execution-role MyImageBuilderDistributionRole
使用映像生成器映像版本 ARN 进行分发

此示例使用编译版本 ARN。你也可以省略尾部的内部版本号 (/1) 来分发该镜像版本的最新版本。

aws imagebuilder distribute-image \ --source-image arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1 \ --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \ --execution-role MyImageBuilderDistributionRole

该命令返回 imageBuildVersionArn 用于分发。跟踪其进度与跟踪构建的方法相同,请参阅 列出映像和构建版本。

重试失败的图像

如果图像在测试或分发阶段出现故障,请使用 重试镜像 命令( RetryImage API) 从失败的阶段一开始就重新运行图像。该阶段的步骤再次运行。如果先前尝试的 AMI 副本在目标区域和账户中仍然可用,Image Builder 会重复使用该副本,而不是再次复制 AMI。Image Builder 重复使用原始执行角色、分发配置和设置,因此您无需重建映像。重试将使用相同的执行角色,因此您对该角色所做的任何权限修正都适用于重试。

先决条件

在重试失败的图像之前,请验证以下内容。重试计入您的并发映像构建配额,如果您已经达到该配额,Image Builder 会拒绝重试。

  • 该图像位于 FAILED 要么 CANCELLED 状态,并且它在测试或分发阶段失败或被取消。您无法重试成功或仍在处理中的映像,也无法重试在任何其他阶段失败或被取消的图像。

  • 该镜像是在过去 30 天内创建的。

  • 该图像是一个 AMI-based 图片。你无法重试容器镜像。

  • 该图像尚未达到最大重试次数。映像生成器允许每张图像最多重试 10 次。

  • 您已经确定并解决了失败的根本原因。查看图片的登录信息 CloudWatch 错误详细信息日志。

  • 你有权打电话 imagebuilder:RetryImage 在要重试的映像构建版本上。

  • 对于跨账户分发失败,请验证 EC2ImageBuilderDistributionCrossAccountRole 在目标账户中有 Ec2ImageBuilderCrossAccountDistributionAccess policy 已附加管理策略。有关更多信息,请参阅 使用 Image Builder 设置跨账户 AMI 分配。

Amazon Web Services 管理控制台

要在映像生成器控制台中重试失败的映像,请执行以下步骤:

  1. 打开 EC2 映像生成器控制台,网址为 https://console.aws.amazon.com/imagebuilder/。

  2. 选择 图片 从导航窗格中,然后选择失败的映像构建版本。

  3. 选择 重试镜像。仅当图像处于失败或取消状态时,此操作才可用。

Amazon CLI

提供失败映像的映像编译版本 ARN:

aws imagebuilder retry-image \ --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1

分发工作流程

分发工作流程是一种补充构建和测试工作流程的工作流类型。分发工作流程将分发阶段定义为一系列步骤,这使您可以逐步查看和控制 Image Builder 分发 AMI 的方式。本节介绍的步骤适用于 AMI 输出图像。

在分发工作流程中,您可以包括执行以下操作的步骤:

  • 跨区域和账户复制和共享 AMI。

  • 修改分布式 AMI 的图像属性,例如启动权限。

  • 应用其他映像配置。

  • 暂停以进行手动批准或使用外部回电 等待行动 步。这使您可以构建分阶段或封闭式部署,例如,分发到测试区域,等待批准,然后继续部署到生产区域。

每个步骤都会报告自己的状态— PENDING, RUNNING, WAITING (仅限等待行动步骤), COMPLETED, FAILED, SKIPPED,或 CANCELLED — 然后 Image Builder 会将步骤级别的详细信息发送给您 CloudWatch 日志组。这个步骤比它跑得更长 timeoutSeconds 价值报告 FAILED。图像生成器还会发出 EventBridge 关键点的事件——例如,当图像改变状态时,以及等待操作的步骤暂停输入时。有关活动的完整列表,请参阅 Image Builder 发送的事件消息。

要了解如何创建和自定义工作流程,包括 YAML 文档格式和可用的步骤操作,请参阅 管理映像生成器映像的构建、测试和分发工作流程。