本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Image Builder 配置自定义映像
配置资源是构成映像管道的构建基块，也是这些管道生成的映像。本章介绍创建、维护和共享 Image Builder 资源，包括组件、配方和映像，以及基础架构配置和分配设置。
**注意**
为了帮助您管理 Image Builder 资源，您可通过标签 的形式为每个资源分配元数据。您使用标签按照不同方式（例如按用途、所有者或环境）对 AWS 资源进行分类。这在您有许多相同类型的资源时会非常有用。您可以根据分配到特定资源的标签来更轻松地识别该资源。
有关使用 Image Builder 命令为资源添加标签的更多信息 AWS CLI，请参阅本指南的[标记资源](tag-resources.md)章节。
**Topics**
+ [
# 在 Image Builder 中管理配方
](manage-recipes.md)
+ [
# 管理 Image Builder 基础设施配置
](manage-infra-config.md)
+ [
# 管理 Image Builder 分配设置
](manage-distribution-settings.md)
# 在 Image Builder 中管理配方
EC2 Image Builder 配方定义了用作创建新图像的起点的基础图像，以及为自定义图像和验证一切是否按预期运行而添加的一组组组件。Image Builder 为每个组件提供版本自动选择。默认情况下，您最多可以对配方应用 20 个组件。这包括构建和测试组件。
在您创建配方后，您不能再修改或替换它。要在创建配方后更新组件，您必须创建新的配方或配方版本。您可以将标签应用到现有配方。有关使用 Image Builder 命令为资源添加标签的更多信息 AWS CLI，请参阅本指南的[标记资源](tag-resources.md)部分。
**提示**
您可以在配方中使用 Amazon 托管组件，也可以开发自己的自定义组件。有关更多信息，请参阅 [为 Image Builder 映像开发自定义组件](create-custom-components.md)。对于创建输出的图像配方 AMIs，您也可以使用 AWS Marketplace 图片产品和组件。有关与 AWS Marketplace 产品集成的更多信息，请参阅[AWS Marketplace 在 Image Builder 中集成](integ-marketplace.md)。
本节介绍如何列出、查看和创建配方。
**Topics**
+ [
# 列出和查看映像配方的详细信息
](image-recipe-details.md)
+ [
# 列出和查看容器配方详细信息
](container-recipe-details.md)
+ [
# 创建映像配方的新版本
](create-image-recipes.md)
+ [
# 创建新版本的容器配方
](create-container-recipes.md)
+ [
## 清理资源
](#recipes-cleanup)
# 列出和查看映像配方的详细信息
本节介绍您可以通过多种方式查找有关您的 EC2 Image Builder 映像配方的信息并查看详细信息。
**Topics**
+ [
## 通过控制台列出映像配方
](#list-image-recipes-console)
+ [
## 列出来自 AWS CLI
](#cli-list-image-recipes)
+ [
## 通过控制台查看映像配方详细信息
](#view-image-recipe-details-console)
+ [
## 从中获取图片配方详情 AWS CLI
](#cli-get-image-recipe)
+ [
## 从中获取图片配方政策详情 AWS CLI
](#cli-get-image-recipe-policy)
## 通过控制台列出映像配方
要在 Image Builder 控制台中查看在您账户下创建的映像配方列表，请按照以下步骤操作：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 在导航窗格中，选择**映像配方**。这会显示在您账户下创建的映像配方列表。
1. 要查看详细信息或创建新的配方版本，请选择**配方名称**链接。这将打开配方的详细视图。
**注意**
您也可以选中**配方名称** 旁边的复选框，然后选择 **查看详细信息**。
## 列出来自 AWS CLI
以下示例说明了如何使用 AWS CLI列出所有映像配方。
```
aws imagebuilder list-image-recipes
```
## 通过控制台查看映像配方详细信息
要使用 Image Builder 控制台查看特定映像配方的详细信息，请按照 [通过控制台列出映像配方](#list-image-recipes-console) 中所述的步骤选择要查看的映像配方。
在配方详细信息页面上，您可以：
+ 删除配方。有关在 Image Builder 中删除资源的更多信息，请参阅 [删除过期或未使用的 Image Builder 资源](delete-resources.md)。
+ 创建新版本。
+ 从配方中创建管道。选择**根据此配方中创建管道**后，您将进入管道向导。有关使用管道向导创建 Image Builder 管道的更多信息，请参阅 [教程：通过 Image Builder 控制台向导使用输出 AMI 创建映像管道](start-build-image-pipeline.md)
**注意**
当您根据现有配方创建管道时，创建新配方的选项不可用。
## 从中获取图片配方详情 AWS CLI
以下示例说明了如何指定 Amazon 资源名称（ARN）以通过使用 **imagebuilder** CLI 命令获取映像配方详细信息。
```
aws imagebuilder get-image-recipe --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03
```
## 从中获取图片配方政策详情 AWS CLI
以下示例说明了如何指定 ARN 以通过使用 **imagebuilder** CLI 命令获取映像配方策略详细信息。
```
aws imagebuilder get-image-recipe-policy --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03
```
# 列出和查看容器配方详细信息
本节介绍如何查找有关 EC2 Image Builder 容器配方的信息并查看详细信息。
**Topics**
+ [
## 在控制台中列出容器配方
](#list-container-recipes-console)
+ [
## 使用列出容器配方 AWS CLI
](#cli-list-container-recipes)
+ [
## 在控制台中查看容器配方详细信息
](#view-container-recipe-details-console)
+ [
## 使用获取容器配方详情 AWS CLI
](#cli-get-container-recipe)
+ [
## 通过获取容器配方政策的详细信息 AWS CLI
](#cli-get-container-recipe-policy)
## 在控制台中列出容器配方
要在 Image Builder 控制台中查看在您的账户下创建的容器配方列表，请按照以下步骤操作：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**容器配方**。这将显示在您的账户下创建的容器配方列表。
1. 要查看详细信息或创建新的配方版本，请选择**配方名称**链接。这将打开配方的详细视图。
**注意**
您也可以选中**配方名称**旁边的框，然后选择**查看详细信息**。
## 使用列出容器配方 AWS CLI
以下示例说明了如何使用 AWS CLI列出您的所有容器配方。
```
aws imagebuilder list-container-recipes
```
## 在控制台中查看容器配方详细信息
要使用 Image Builder 控制台查看特定容器配方的详细信息，请选择要查看的容器配方，然后执行 [在控制台中列出容器配方](#list-container-recipes-console) 中所述的步骤。
在配方详细悉心页面上，您可以执行以下操作：
+ 删除配方。有关如何在 Image Builder 中删除资源的更多信息，请参阅 [删除过期或未使用的 Image Builder 资源](delete-resources.md)。
+ 创建新版本。
+ 从配方中创建管道。选择**从此配方中创建管道**后，您将进入管道向导。有关如何使用管道向导创建 Image Builder 管道的更多信息，请参阅 [教程：通过 Image Builder 控制台向导使用输出 AMI 创建映像管道](start-build-image-pipeline.md)
**注意**
当您从现有配方中创建管道时，创建新配方的选项不可用。
## 使用获取容器配方详情 AWS CLI
以下示例说明了如何使用 **imagebuilder** CLI 命令通过指定其 ARN 来获取容器配方的详细信息。
```
aws imagebuilder get-container-recipe --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03
```
## 通过获取容器配方政策的详细信息 AWS CLI
以下示例说明了如何使用 **imagebuilder** CLI 命令通过指定其 ARN 来获取容器配方策略的详细信息。
```
aws imagebuilder get-container-recipe-policy --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03
```
# 创建映像配方的新版本
本节介绍如何创建映像配方的新版本。
**Topics**
+ [
## 通过控制台创建新的映像配方版本
](#create-image-recipe-version-console)
+ [
## 使用创建图像配方 AWS CLI
](#create-image-recipe-cli)
+ [
## 在控制台中导入虚拟机 (VM) 作为基础映像
](#import-vm-recipes)
## 通过控制台创建新的映像配方版本
当您创建新的配方版本时，它与创建新配方的操作几乎相同。不同之处在于，在大多数情况下，为匹配基础配方，某些详细信息都是预先选择的。以下列表描述创建新配方和创建现有配方的新版本之间的区别。
**新版本中的基础配方详细信息**
+ **名称** - *不可编辑*。
+ **版本** - 必填。输入要创建的版本号，格式为 *..*。Image Builder 支持食谱的自动版本递增，允许您在配方版本中使用通配符模式。使用通配符版本（例如）创建配方时`1.0.x`，Image Builder 会自动增加版本（例如`1.0.1``1.0.2`、`1.0.3`、等）。这样就无需手动跟踪和增加配方版本。
+ **选择映像**选项 - 已预先选择，但您可以对其进行编辑。如果您更改对基础映像来源的选择，则可能会丢失其他详细信息，这些详细信息取决于您选择的原始选项。
要查看与您的基础映像选择相关的详细信息，请选择与您的选择相匹配的选项卡。
------
#### [ Managed image ]
+ **映像操作系统 (OS)** - *不可编辑*。
+ **映像名称** - 根据您为现有配方所做的基础映像选择的组合进行预先选择。但是，如果您更改**选择映像**选项，则会丢失预先选择的**映像名称**。
+ **自动版本控制选项** - 与您的基础配方*不*匹配。此映像选项默认为**使用选定的操作系统版本**选项。
**重要**
如果您使用语义版本控制来启动管道构建，请确保将此值更改为**使用最新的可用操作系统版本**。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
------
#### [ AWS Marketplace image ]
+ **订阅** — 此选项卡应处于打开状态，并且 AWS Marketplace 应预先选择订阅的图片以匹配您的基本食谱。如果您更改配方用作基础映像的映像，则可能会丢失其他详细信息，这些详细信息取决于您选择的原始映像。
有关 AWS Marketplace 产品的更多信息，请参阅《[买*AWS Marketplace 家指南》*中的 “购买商品](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-subscribing-to-products.html)”。
------
#### [ Custom AMI ]
**AMI 来源**（必填）-输入 AMI ID 或 AWS Systems Manager (SSM) 参数存储参数，其中包含用作基础映像的 AMI ID。SSM 代理必须预先安装在选定的 AMI 中。
+ **AMI ID** — 此设置未预先填入您的原始条目。输入您的基础映像的 AMI ID。示例：`ami-1234567890abcdef1`。
+ **SSM 参数**-输入包含基础映像的 AMI ID 的 SSM 参数存储参数的名称或 ARN。示例：`/ib/test/param` 或 `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`。
------
+ **实例配置** - 设置是预先选择的，但您可以对其进行编辑。
+ **Systems Manager 代理** – 您可以选中或清除此复选框来控制在新映像上安装 Systems Manager 代理。默认情况下，该复选框处于清除状态，以便在新映像中包含 Systems Manager 代理。要从最终映像中移除 Systems Manager 代理，请选中该复选框以使代理不包含在您的 AMI 中。
+ **用户数据** – 当您启动构建实例时，可以使用此区域以提供要运行的命令或命令脚本。但是，此值会替换 Image Builder 可能添加的任何命令，以确保安装 Systems Manager。这些命令包括 Image Builder 通常在创建新映像之前为 Linux 映像运行的清理脚本。
当 Image Builder 启动实例时，用户数据脚本将在组件执行开始之前的云初始化阶段运行。此步骤将记录到实例上的以下文件中：`var/log/cloud-init.log`。
**注意**
如果您要输入用户数据，请确保在您的基础映像上预先安装 Systems Manager 代理，或者将安装的内容包含在您的用户数据中。
对于 Linux 映像，请通过创建一条在用户数据脚本中命名为 `perform_cleanup` 的空文件的命令，以确保运行清理步骤。Image Builder 会检测到此文件，并在创建新映像之前运行清理脚本。有关更多信息和示例脚本，请参阅 [Image Builder 的安全最佳实践](security-best-practices.md)。
+ **工作目录** - 已预先选择，但您可以对其进行编辑。
+ **组件** - 已包含在配方中的组件显示在每个组件列表（构建和测试）末尾的**选定组件**部分中。您可以移除所选组件或对其重新排序，以满足您的需要。
CIS 加固组件未遵循 Image Builder 配方中的标准组件排序规则。CIS 强化组件始终最后运行，以确保基准测试针对您的输出映像运行。
**注意**
构建和测试组件列表根据组件所有者类型显示可用组件。要添加组件，请选择**添加构建组件**，然后选择适用的所有权筛选器。例如，要添加与 AWS Marketplace 产品关联的生成组件，请选择`AWS Marketplace`。这将在控制台界面的右侧打开一个列出 AWS Marketplace 组件的选择面板。
对于 CIS 组件，请选择`Third party managed`。
您可以为自己的所选组件配置以下设置：
+ **版本控制选项** - 已预先选择，但您可以对其进行更改。我们建议您选择**使用最新的可用组件版本**选项，以确保您的映像版本始终使用最新版本的组件。如果您需要在配方中使用特定的组件版本，则可以选择**指定组件版本**，然后在出现的**组件版本**框中输入版本。
+ **输入参数** - 显示组件接受的输入参数。该**值**预先填充了配方先前版本中的值。如果您在此配方中首次使用此组件，并且已为该输入参数定义了默认值，则默认值以灰色文本显示在**值**框中。如果未输入其他值，Image Builder 将使用默认值。
如果需要输入参数，但组件中未定义默认值，则必须提供一个值。如果缺少任何必需的参数且未定义默认值，Image Builder 将不会创建配方版本。
**重要**
组件参数是纯文本值，并且已记录在 AWS CloudTrail中。我们建议您使用 AWS Secrets Manager 或 P AWS Systems Manager arameter Store 来存储您的密钥。有关 Secrets Manager 的更多信息，请参阅*AWS Secrets Manager 用户指南*中的[什么是 Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。有关 AWS Systems Manager Parameter Store 的更多信息，请参阅*《AWS Systems Manager 用户指南》*中的[AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。
要展开**版本控制选项**或**输入参数**的设置，可以选择设置名称旁边的箭头。要展开所有选定组件的所有设置，可以关闭和打开**全部展开**开关。
+ **存储（卷）** - 已预先填好。根卷**设备名称**、**快照**和 **IOPS** 选项不可编辑。但是，您可以更改所有其余设置，例如**大小**。您还可以添加新卷以及加密新卷或现有卷。
要在源区域（运行构建的地方）为 Image Builder 在您的账户下创建的映像进行加密，您必须在映像配方中使用存储卷加密。在该构建的分配阶段运行的加密仅适用于分配给其他账户或地区的映像。
**注意**
如果您对卷使用加密，则必须分别为每个卷选择密钥，即使该密钥与用于根卷的密钥相同也是如此。
**创建新的映像配方版本：**
1. 在配方详细信息页面顶部，选择**创建新版本**。这将带您进入**创建映像配方**页面。
1. 要创建新版本，请进行更改，然后选择**Create recipe**（创建配方）。
您的最终图片最多可以包含来自 AWS Marketplace 图片产品和组件的四个产品代码。如果您选择的基本图片和组件包含四个以上的产品代码，则当您尝试创建配方时，Image Builder 会返回错误。
有关如何在创建映像管道时创建映像配方的更多信息，请参阅本指南的**入门**部分的 [步骤 2：选择配方](start-build-image-pipeline.md#start-build-image-step2)。
## 使用创建图像配方 AWS CLI
要使用中的 Image Builder `create-image-recipe` 命令创建图像配方 AWS CLI，请执行以下步骤：
**先决条件**
在运行本节中的 Image Builder 命令从中创建图像配方之前 AWS CLI，您可以选择创建配方使用的组件。以下步骤中的映像配方示例引用了在本指南 [从中创建自定义组件 AWS CLI](create-component.md#create-component-ib-cli) 部分中创建的示例组件。
如果要在食谱中添加组件，请 ARNs 记下要包含的组件。您也可以创建没有任何组件的配方，用于测试现有 AMIs 或仅限分发的工作流程。
1.
**创建 CLI 输入 JSON 文件**
您可以使用内联命令参数为 **create-image-recipe** 命令提供所有输入。但是，生成的命令可能会很长。为了简化命令，您可以改为提供包含所有配方设置的 JSON 文件。
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 操作请求参数，请参阅《*EC2 Image Builder API 参考*》中的[CreateImageRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImageRecipe.html)命令。
要将数据值作为命令行参数提供，请参阅《*AWS CLI 命令引用*》中指定的参数名称。
以下是这些示例指定的参数的摘要：
+ **名称**（字符串，必填项） - 映像配方的名称。
+ **描述**（字符串）- 映像配方的描述。
+ **parentImage** （字符串，必填项）- 映像配方用作自定义映像基础的映像。您可以使用以下选项之一来指定父映像：
+ AMI ID
+ Image Builder 图片资源 ARN
+ AWS Systems Manager (SSM) 参数存储参数，前缀为`ssm:`，后跟参数名称或 ARN。
+ AWS Marketplace 产品编号
**注意**
Linux 和 macOS 示例使用 Image Builder AMI，Windows 示例使用 ARN。
+ **SemanticVersion** *（字符串，必填）-输入要按格式创建的版本号。 。 *。Image Builder 支持食谱的自动版本递增，允许您在配方版本中使用通配符模式。使用通配符版本（例如）创建配方时`1.0.x`，Image Builder 会自动增加版本（例如`1.0.1``1.0.2`、`1.0.3`、等）。这样就无需手动跟踪和增加配方版本。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
+ **组件**（数组，可选）-包含`ComponentConfiguration`对象数组。组件是可选的-您可以创建没有任何组件的配方，用于测试或分发工作流程：
**注意**
Image Builder 按照您在配方中指定的顺序安装组件。但是，CIS 强化组件始终最后运行，以确保基准测试针对您的输出映像运行。
+ **componentARN**（字符串，必填）– 组件 ARN。
**提示**
要使用其中一个示例来创建自己的图像配方，必须将该示例 ARNs 替换 ARNs 为用于配方的组件。
+ **参数**（对象数组）- 包含 `ComponentParameter` 对象数组。如果需要输入参数，但组件中未定义默认值，则必须提供一个值。如果缺少任何必需的参数且未定义默认值，Image Builder 将不会创建配方版本。
**重要**
组件参数是纯文本值，并且已记录在 AWS CloudTrail中。我们建议您使用 AWS Secrets Manager 或 P AWS Systems Manager arameter Store 来存储您的密钥。有关 Secrets Manager 的更多信息，请参阅*AWS Secrets Manager 用户指南*中的[什么是 Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。有关 AWS Systems Manager Parameter Store 的更多信息，请参阅*《AWS Systems Manager 用户指南》*中的[AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。
+ **名称**（字符串，必填）- 要设置的组件参数的名称。
+ **值**（字符串数组，必填）- 包含用于设置指定组件参数值的字符串数组。如果为组件定义了默认值，但未提供其他值，则 AWSTOE 使用默认值。
+ **additionalInstanceConfiguration**(object)-为您的编译实例指定其他设置并启动脚本。
+ **systemsManagerAgent**（对象）-包含编译实例上的 Systems Manager 代理的设置。
+ **uninstallAfterBuild**（布尔值）-控制在创建新 AMI 之前是否从最终构建映像中删除 Systems Manager 代理。如果将此选项设置为 `true`，则从最终映像中移除该代理。如果将此选项设置为 `false`，则保留该代理，以便将它包含在新 AMI 中。默认值为 `false`。
**注意**
如果 JSON 文件中未包含该 `uninstallAfterBuild` 属性，并且满足以下条件，则 Image Builder 会从最终映像中移除 Systems Manager 代理，使其在 AMI 中不可用：
`userDataOverride` 为空或已从 JSON 文件中省略。
对于未在基础映像上预装代理的操作系统，Image Builder 会自动在构建实例上安装 Systems Manager 代理。
+ **userDataOverride**（字符串）-提供启动构建实例时要运行的命令或命令脚本。
**注意**
用户数据始终采用 base 64 编码。例如，以下命令被编码为 `IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==`：
```
#!/bin/bash
mkdir -p /var/bb/
touch /var
```
Linux 示例使用此编码值。
------
#### [ Linux ]
以下示例中的基础映像（`parentImage` 属性）是 AMI。使用 AMI 时，您必须具有访问该 AMI 的权限，并且 AMI 必须位于源区域（与 Image Builder 运行命令的区域相同）。将文件另存为 `create-image-recipe.json`，并在 **create-image-recipe** 命令中使用。
```
{
"name": "BB Ubuntu Image recipe",
"description": "Hello World image recipe for Linux.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/bb$"
}
],
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
},
"userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg=="
}
}
```
------
#### [ Windows ]
以下示例引用最新版本的 Windows Server 2016 英文版全基础映像。此示例中的 ARN 引用基于您指定的语义版本过滤器的最新图像:. `arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x`
```
{
"name": "MyBasicRecipe",
"description": "This example image recipe creates a Windows 2016 image.",
"parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/2019.12.02/1"
},
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-imported-component/1.0.0/1"
}
]
}
```
**注意**
要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
------
#### [ macOS ]
以下示例中的基础映像（`parentImage` 属性）是 AMI。使用 AMI 时，您必须具有访问该 AMI 的权限，并且 AMI 必须位于源区域（与 Image Builder 运行命令的区域相同）。将文件另存为 `create-image-recipe.json`，并在 **create-image-recipe** 命令中使用。
```
{
"name": "macOS Catalina Image recipe",
"description": "Hello World image recipe for macOS.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/catalina$"
}
],
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
},
"userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg=="
}
}
```
------
**示例：不含组件的食谱**
您可以创建没有任何组件的配方，用于测试现有 AMIs 或仅限分发的工作流程。以下示例显示了一个使用现有 AMI 而不应用任何其他组件的配方：
```
{
"name": "Test Distribution Recipe",
"description": "Recipe for testing and distributing existing AMI without modifications.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
}
}
}
```
1.
**创建配方**
使用以下命令以创建配方。在 `--cli-input-json` 参数中提供您在上一步中创建的 JSON 文件的名称：
```
aws imagebuilder create-image-recipe --cli-input-json file://create-image-recipe.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
您的最终图片最多可以包含来自 AWS Marketplace 图片产品和组件的四个产品代码。如果您选择的基础图片和组件包含四个以上的产品代码，则在运行`create-image-recipe`命令时，Image Builder 会返回错误。
## 在控制台中导入虚拟机 (VM) 作为基础映像
在本节中，我们将重点介绍如何导入虚拟机 (VM) 作为映像配方的基础映像。这里我们不介绍创建配方或配方版本所涉及的其他步骤。有关在 Image Builder 控制台中使用管道创建向导创建新映像配方的其他步骤，请参阅 [管道向导：创建 AMI](start-build-image-pipeline.md)。有关创建新映像配方或配方版本的其他步骤，请参阅 [创建映像配方的新版本](#create-image-recipes)。
要在 Image Builder 控制台中导入虚拟机 (VM) 作为映像配方的基础映像，请按照以下步骤以及任何其他必需的步骤来创建您的配方或配方版本。
1. 在基础映像的**选择映像**部分中，选择**导入基础映像**选项。
1. 像往常一样选择**映像操作系统 (OS)**和**操作系统 (OS) 版本**。
### 虚拟机导入配置
当您从虚拟化环境中导出虚拟机时，该过程会创建一个或多个磁盘容器文件，这些文件充当虚拟机环境、设置和数据的快照。您可以使用这些文件导入虚拟机作为映像配方的基本映像。有关 VMs 在 Image Builder 中导入的更多信息，请参阅 [导入和导出 VM 映像](vm-import-export.md)
要指定导入源的位置，请执行以下步骤：
**导入源**
在**磁盘容器 1 **部分中指定要导入的第一个虚拟机映像磁盘容器或快照的来源。
1. **源** – 可以是 S3 存储桶或 EBS 快照。
1. **选择磁盘的 S3 位置** – 输入 Amazon S3 中存储磁盘映像的位置。要浏览位置，请选择**浏览 S3**。
1. 要添加磁盘容器，请选择**添加磁盘容器**。
**IAM 角色**
要将 IAM 角色与您的虚拟机导入配置相关联，请从 **IAM 角色**下拉列表中选择该角色，或者选择**创建新角色**来创建一个新角色。如果您创建了新角色，IAM 角色控制台页面将在单独的标签页中打开。
#### 高级设置 – *可选*
以下设置可选：使用这些设置，您可以为导入创建的基本映像配置加密、许可、标签等。
**General**
1. 为基本映像指定一个唯一的**名称**。如果不输入任何值，则基础映像将继承该配方名称。
1. 指定基础映像的**版本**。采用以下格式：`..`。如果不输入任何值，则基础映像将继承该配方版本。
1. 您也可以为基础映像输入**描述**。
**基础映像架构**
要指定虚拟机导入源的架构，请从**架构**列表中选择一个值。
**加密**
如果您的虚拟机磁盘映像已加密，则必须提供用于导入过程的密钥。要 AWS KMS key 为导入指定一个，请从**加密（KMS 密钥）**列表中选择一个值。该列表包含您的账户在当前区域中有权访问的 KMS 密钥。
**许可证管理**
导入虚拟机时，导入过程会自动检测虚拟机操作系统并将相应的许可证应用于基本映像。根据您的操作系统平台，许可证类型如下：
+ **包含许可证** — 适用于您的平台的相应 AWS 许可证将应用于您的基本映像。
+ **自带许可（BYOL）** - 保留源自虚拟机的许可证（如果适用）。
要将使用创建的许可证配置附加 AWS License Manager 到您的基础映像，请从**许可证配置名称**列表中进行选择。有关 License Manager 的更多信息，[请参阅使用 AWS License Manager]()
**注意**
许可证配置包含基于您的企业协议条款的许可规则。
Linux 仅支持 BYOL 许可证。
**标签（基本映像）**
标签使用键值对为您的 Image Builder 资源分配可搜索的文本。要为导入的基础映像指定标签，请使用**键**和**值**框输入键值对。
要添加标签，请选择 **Add tag**（添加标签）。要删除标签，请选择 **Remove tag**（删除标签）。
# 创建新版本的容器配方
本节展示了如何创建创建新版本的容器配方。
**Topics**
+ [
## 使用控制台创建新的容器配方版本
](#create-container-recipe-version)
+ [
## 使用创建容器配方 AWS CLI
](#create-container-recipe-cli)
## 使用控制台创建新的容器配方版本
创建新版本的容器配方与创建新配方几乎相同。不同之处在于，在大多数情况下，为匹配基础配方，某些详细信息都是预先选择的。以下列表描述创建新配方和创建现有配方的新版本之间的区别。
**配方详细信息**
+ **名称** - *不可编辑*。
+ **版本** - 必填。此详细信息未预先填充当前版本或任何类型的序列。以 *major.minor.patch* 格式输入要创建的版本号。如果该版本已经存在，则会遇到错误。
**基础映像**
+ **选择映像**选项 - 预先选择，但可以编辑。如果您更改对基础映像来源的选择，则可能会丢失其他详细信息，这些详细信息取决于您选择的原始选项。
对于 Docker 容器镜像，您可以从托管的公共镜像 DockerHub、Amazon ECR 中的现有容器镜像或亚马逊管理的容器镜像中进行选择。要查看与您的基础映像选择相关的详细信息，请选择与您的选择相匹配的选项卡。
------
#### [ Managed images ]
+ **映像操作系统 (OS)** - *不可编辑*。
+ **映像名称** - 根据您为现有配方所做的基础映像选择的组合进行预先选择。但是，如果您更改**选择映像**选项，则会丢失预先选择的**映像名称**。
+ **自动版本控制选项** - 与您的基础配方*不*匹配。自动版本控制选项默认为**使用选定的操作系统版本**选项。
**重要**
如果您使用语义版本控制来启动管道构建，请确保将此值更改为**使用最新的可用操作系统版本**。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
------
#### [ ECR image ]
+ **映像操作系统 (OS)** - 预先选择，但可编辑。
+ **操作系统版本** - 预先选择，但可编辑。
+ **ECR 映像 ID** – 已预先填充，但可编辑。
------
#### [ Docker Hub image ]
+ **映像操作系统 (OS)** - *不可编辑*。
+ **操作系统版本** - 预先选择，但可编辑。
+ **Docker 映像 ID** – 已预先填充，但可以编辑。
------
**实例配置**
+ **AMI 来源**（必填）-确定要用作容器构建和测试实例基础映像的自定义 AMI。这可以是 AMI ID 或包含 AMI ID 的 AWS Systems Manager (SSM) 参数存储参数。
+ **AMI ID** — 此设置未预先填入您的原始条目。输入您的基础映像的 AMI ID。示例：`ami-1234567890abcdef1`。
+ **SSM 参数**-输入包含基础映像的 AMI ID 的 SSM 参数存储参数的名称或 ARN。示例：`/ib/test/param` 或 `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`。
+
**存储（卷）**
**EBS 第 1 卷（AMI 根）**— 已预先填充。您无法编辑根卷**设备名称**、**快照**或 **IOPS** 选项。但是，您可以更改所有其余设置，例如**大小**。您还可以添加新卷。
**注意**
如果您指定了从另一个账户共享的基本 AMI，则指定的任何辅助卷的快照还必须与您的账户共享。
**工作目录**
+ **工作目录路径** – 已预先填充，但可编辑。
**组件**
+ **组件** - 已包含在配方中的组件显示在每个组件列表（构建和测试）末尾的**选定组件**部分中。您可以移除所选组件或对其重新排序，以满足您的需要。
CIS 加固组件未遵循 Image Builder 配方中的标准组件排序规则。CIS 强化组件始终最后运行，以确保基准测试针对您的输出映像运行。
**注意**
构建和测试组件列表根据组件所有者类型显示可用组件。要添加组件，请选择**添加构建组件**，然后选择适用的所有权筛选器。例如，要添加与 AWS Marketplace 产品关联的构建组件，请选择`AWS Marketplace`。这将在控制台界面的右侧打开一个列出 AWS Marketplace 组件的选择面板。
对于 CIS 组件，请选择`Third party managed`。
您可以为自己的所选组件配置以下设置：
+ **版本控制选项** - 已预先选择，但您可以对其进行更改。我们建议您选择**使用最新的可用组件版本**选项，以确保您的映像版本始终使用最新版本的组件。如果您需要在配方中使用特定的组件版本，则可以选择**指定组件版本**，然后在出现的**组件版本**框中输入版本。
+ **输入参数** - 显示组件接受的输入参数。该**值**预先填充了配方先前版本中的值。如果您在此配方中首次使用此组件，并且已为该输入参数定义了默认值，则默认值以灰色文本显示在**值**框中。如果未输入其他值，Image Builder 将使用默认值。
如果需要输入参数，但组件中未定义默认值，则必须提供一个值。如果缺少任何必需的参数且未定义默认值，Image Builder 将不会创建配方版本。
**重要**
组件参数是纯文本值，并且已记录在 AWS CloudTrail中。我们建议您使用 AWS Secrets Manager 或 P AWS Systems Manager arameter Store 来存储您的密钥。有关 Secrets Manager 的更多信息，请参阅*AWS Secrets Manager 用户指南*中的[什么是 Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。有关 AWS Systems Manager Parameter Store 的更多信息，请参阅*《AWS Systems Manager 用户指南》*中的[AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。
要展开**版本控制选项**或**输入参数**的设置，可以选择设置名称旁边的箭头。要展开所有选定组件的所有设置，可以关闭和打开**全部展开**开关。
**Dockerfile 模板**
+ **Dockerfile 模板** – 已预先填充，但可编辑。您可以指定以下任意上下文变量，Image Builder 在运行时将这些变量替换为构建信息。
**parentImage（必需）**
在构建时，此变量会解析为配方的基础映像。
示例：
```
FROM
{{{ imagebuilder:parentImage }}}
```
**environments（如果指定了组件，则为必需）**
此变量将解析为运行组件的脚本。
示例：
```
{{{ imagebuilder:environments }}}
```
**components（可选）**
Image Builder 解析容器配方中包含的组件的构建和测试组件脚本。此变量可以置于 Dockerfile 中的任意位置，在 environments 变量之后。
示例：
```
{{{ imagebuilder:components }}}
```
**目标存储库**
+ **目标存储库名称** – 如果您的管道的分发配置中没有为管道运行区域（区域 1）指定其他存储库，则输出映像存储在 Amazon ECR 存储库。
**创建新的容器配方版本：**
1. 在容器配方详细信息页面的顶部，选择**Create new version**（创建新版本）。您将进入容器配方的**创建配方**页面。
1. 要创建新版本，请进行更改，然后选择**Create recipe**（创建配方）。
有关如何在创建映像管道时创建容器配方的更多信息，请参阅本指南的**入门**章节中的[步骤 2：选择配方](start-build-container-pipeline.md#start-build-container-step2)。
## 使用创建容器配方 AWS CLI
要使用中的`imagebuilder create-container-recipe`命令创建 Image Builder 容器配方 AWS CLI，请执行以下步骤：
**先决条件**
在运行本节中的 Image Builder 命令使用创建容器配方之前 AWS CLI，必须创建配方将使用的组件。以下步骤中的容器配方示例引用了在本指南 [从中创建自定义组件 AWS CLI](create-component.md#create-component-ib-cli) 章节中创建的示例组件。
创建组件后，或者如果您使用的是现有组件，请记下要ARNs 包含在配方中的组件。
1.
**创建 CLI 输入 JSON 文件**
您可以使用内联命令参数为 **create-container-recipe** 命令提供所有输入。但是，生成的命令可能会很长。为了简化命令，您可以改为提供一个包含所有容器配方设置的 JSON 文件
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 操作请求参数，请参阅《*EC2 Image Builder API 参考*》中的[CreateContainerRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateContainerRecipe.html)命令。
要将数据值作为命令行参数提供，请参阅《*AWS CLI 命令引用*》中指定的参数名称。
以下是此示例中参数的摘要：
+ **组件**（对象数组，必填）- 包含 `ComponentConfiguration` 对象数组。必须指定至少一个构建组件：
**注意**
Image Builder 按照您在配方中指定的顺序安装组件。但是，CIS 强化组件始终最后运行，以确保基准测试针对您的输出映像运行。
+ **componentARN**（字符串，必填）– 组件 ARN。
**提示**
要使用该示例来创建自己的容器配方，请将该 ARNs 示例 ARNs 替换为用于配方的组件。其中包括每个版本的 AWS 区域、名称和版本号。
+ **参数**（对象数组）- 包含 `ComponentParameter` 对象数组。如果需要输入参数，但组件中未定义默认值，则必须提供一个值。如果缺少任何必需的参数且未定义默认值，Image Builder 将不会创建配方版本。
**重要**
组件参数是纯文本值，并且已记录在 AWS CloudTrail中。我们建议您使用 AWS Secrets Manager 或 P AWS Systems Manager arameter Store 来存储您的密钥。有关 Secrets Manager 的更多信息，请参阅*AWS Secrets Manager 用户指南*中的[什么是 Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。有关 AWS Systems Manager Parameter Store 的更多信息，请参阅*《AWS Systems Manager 用户指南》*中的[AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。
+ **名称**（字符串，必填）- 要设置的组件参数的名称。
+ **值**（字符串数组，必填）- 包含用于设置指定组件参数值的字符串数组。如果为组件定义了默认值，但未提供其他值，则 AWSTOE 使用默认值。
+ **containerType**（字符串，必填）- 要创建的容器的类型。有效值包括 `DOCKER`。
+ **dockerfileTemplateData**（字符串）— 用于构建映像的 Dockerfile 模板，表示为内联数据 blob。
+ **名称**（字符串，必填）- 容器配方的名称。
+ **描述**（字符串）- 容器配方的描述。
+ p@@ **arentImag** e（字符串，必填）— 要在容器配方中用作自定义映像基线的 Docker 容器镜像。
+ 公共图片托管在 DockerHub
+ 亚马逊 ECR 中的现有容器镜像
+ 亚马逊管理的容器镜像
+ **platformOverride**（字符串）– 指定使用自定义基础映像时的操作系统平台。
+ **semanticVersion**（字符串，必填）– 容器配方的语义版本按以下格式指定，每个位置都有数值以表示特定版本：*..*。例如，`1.0.0` 就是一个示例。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
+ **标签**（字符串映射）– 附加到容器配方的标签。
+ **instanceConfiguration**（对象）– 可用于配置实例以构建和测试容器映像的一组选项。
+ **imag** e（字符串）— 容器构建和测试实例的基础镜像。它可以包含 AMI ID，也可以指定 AWS Systems Manager (SSM) 参数存储参数，前缀为参数名称或 ARN`ssm:`，其前缀为参数名称或 ARN。如果您使用 SSM 参数，则该参数值必须包含 AMI ID。如果您未指定基础映像，Image Builder 会使用相应的 Amazon ECS 优化的 AMI 作为基础映像。
+ **blockDeviceMappings**（对象数组）— 定义要连接的块设备，以便从**image**参数中指定的 Image Builder AMI 构建实例。
+ **deviceName**（字符串）- 这些映射适用的设备。
+ **ebs**（对象）– 用于管理此映射的特定于 Amazon EBS 的配置。
+ **deleteOnTermination**（布尔值）-用于配置关联设备终止时的删除。
+ **已加密**（布尔值）- 用于配置设备加密。
+ **volumeSize**（整数）- 用于覆盖设备的卷大小。
+ **volumeType**（字符串）- 用于覆盖设备的卷类型。
+ **targetRepository**（对象，必填）– 如果管道的分发配置中没有为管道运行区域（区域 1）指定其他存储库，则为容器映像的目标存储库。
+ **repositoryName**（字符串，必填）– 存储输出容器映像的容器存储库的名称。此名称以存储库位置作为前缀。
+ **服务**（字符串，必填）– 指定注册此映像的服务。
+ **workingDirectory**（字符串）– 构建和测试工作流期间使用的工作目录。
```
{
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/helloworldal2/x.x.x"
}
],
"containerType": "DOCKER",
"description": "My Linux Docker container image",
"dockerfileTemplateData": "FROM {{{ imagebuilder:parentImage }}}\n{{{ imagebuilder:environments }}}\n{{{ imagebuilder:components }}}",
"name": "amazonlinux-container-recipe",
"parentImage": "amazonlinux:latest",
"platformOverride": "Linux",
"semanticVersion": "1.0.2",
"tags": {
"sometag" : "Tag detail"
},
"instanceConfiguration": {
"image": "ami-1234567890abcdef1",
"blockDeviceMappings": [
{
"deviceName": "/dev/xvda",
"ebs": {
"deleteOnTermination": true,
"encrypted": false,
"volumeSize": 8,
"volumeType": "gp2"
}
}
]
},
"targetRepository": {
"repositoryName": "myrepo",
"service": "ECR"
},
"workingDirectory": "/tmp"
}
```
1.
**创建配方**
使用以下命令以创建配方。在 `--cli-input-json` 参数中提供您在上一步中创建的 JSON 文件的名称：
```
aws imagebuilder create-container-recipe --cli-input-json file://create-container-recipe.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
## 清理资源
为避免意外费用，请务必清理根据本指南中的示例创建的资源和管道。有关删除 Image Builder 中的资源的更多信息，请参阅 [删除过期或未使用的 Image Builder 资源](delete-resources.md)。
# 管理 Image Builder 基础设施配置
您可以使用基础设施配置，以指定 Image Builder 用于构建和测试 EC2 Image Builder 映像的 Amazon EC2 基础设施。基础设施设置包括：
+ 构建和测试基础设施的实例类型。我们建议指定多种实例类型，因为这允许 Image Builder 从具有足够容量的池中启动实例。这可以减少临时的生成失败次数。
对于 Mac 映像，可能需要选择原生支持 macOS 操作系统的实例类型。有关更多信息，请参阅《Amazon EC2 用户指南》**中的 [Amazon EC2 Mac 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html)。
+ 实例放置设置，您可以在其中指定从映像启动的实例应保存到的主机、主机置放群组或可用区。
+ 实例配置文件为您的构建和测试实例提供执行自定义活动所需的权限。例如，如果您具有一个从 Amazon S3 中检索资源的组件，则实例配置文件需要具有访问这些文件的权限。该实例配置文件还需要具备能使EC2 Image Builder 成功与实例进行通信的最低权限。有关更多信息，请参阅 [准备好使用 Image Builder 构建自定义映像](set-up-ib-env.md)。
+ 管道构建和测试实例的 VPC、子网和安全组。
+ Image Builder 存储构建和测试应用程序日志的 Amazon S3 位置。如果配置日志记录，在基础设施配置中指定的实例配置文件必须具有目标存储桶 (`arn:aws:s3:::BucketName/*`) 的 `s3:PutObject` 权限。
+ 在您的构建失败并且您将 `terminateInstanceOnFailure` 设置为 `false` 时，Amazon EC2 密钥对可以让您登录到实例以进行故障排除。
+ Image Builder 发送事件通知的 SNS 主题。有关 Image Builder 如何与 Amazon SNS 集成的更多信息，请参阅 [Image Builder 中的 Amazon SNS 集成](integ-sns.md)。
**注意**
如果 SNS 主题已加密，则加密此主题的密钥必须位于 Image Builder 服务运行的账户中。Image Builder 无法向使用其他账户密钥进行加密的 SNS 主题发送通知。
您可以使用 Image Builder 控制台，通过 Image Builder API 或 AWS CLI中的 **imagebuilder** 命令来创建和管理基础设施配置。
**Topics**
+ [
# 列出并查看有关基础设施配置的详细信息
](infra-config-details.md)
+ [
# 创建基础设施配置
](create-infra-config.md)
+ [
# 更新基础设施配置
](update-infra-config.md)
+ [
# Image Builder 和 AWS PrivateLink 接口 VPC 终端节点
](vpc-interface-endpoints.md)
**提示**
在您具有相同类型的许多资源时，制作标签可帮助您根据分配给特定资源的标签来识别它。有关使用 Image Builder 命令为资源添加标签的更多信息 AWS CLI，请参阅本指南的[标记资源](tag-resources.md)部分。
# 列出并查看有关基础设施配置的详细信息
本部分描述您可以通过多种方式查找有关您的 EC2 Image Builder 基础设施配置的信息和查看详细信息。
**Topics**
+ [
## 从中列出基础架构配置 AWS CLI
](#cli-list-infrastructure-configurations)
+ [
## 从中获取基础架构配置的详细信息 AWS CLI
](#cli-get-infrastructure-configuration-details)
## 从中列出基础架构配置 AWS CLI
以下示例说明了如何使用 AWS CLI中的 **[list-infrastructure-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-infrastructure-configurations.html)** 列出所有基础设施配置。
```
aws imagebuilder list-infrastructure-configurations
```
## 从中获取基础架构配置的详细信息 AWS CLI
以下示例说明如何使用中的**[get-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-infrastructure-configuration.html)**命令通过指定基础设施配置的 Amazon 资源名称 (ARN) 来获取基础设施配置的详细信息。 AWS CLI
```
aws imagebuilder get-infrastructure-configuration --infrastructure-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration
```
# 创建基础设施配置
本节介绍如何使用 Image Builder 控制台或中的**imagebuilder**命令 AWS CLI 来创建基础架构配置，
------
#### [ Console ]
要从 Image Builder 控制台创建基础设施配置资源，请执行以下步骤：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中选择**基础设施配置**。
1. 选择**创建基础设施配置**。
1. 在 **概述** 部分中，输入以下必要信息：
+ 输入基础设施配置资源的**名称**。
+ 选择希望与构建和测试实例上的组件权限实例配置文件关联的 **IAM 角色**。Image Builder 使用这些权限来下载和运行您的组件 CloudWatch、向其上传日志，以及执行配方中组件指定的任何其他操作。
1. 在 **AWS 基础设施**面板中，您可以配置其余可用的基础设施设置。输入以下必要信息：
+ **实例类型**：您可以为此构建指定一个或多个实例类型。该服务将根据可用性选择其中一种实例类型。
**注意**
Mac 实例运行于专属主机上的 `.metal` 实例类型。您的实例类型必须与为运行它的主机定义的类型之一相匹配。有关 Mac 实例的更多信息以及原生支持 macOS 操作系统的实例类型列表，请参阅《Amazon EC2 用户指南》**中的 [Amazon EC2 Mac 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html)。
+ **SNS 主题（可选）** - 选择一个 SNS 主题来接收来自 EC2 Image Builder 的通知和提醒。
如果您没有为以下设置提供值，则这些设置将使用特定于服务的默认值（如适用）。
+ **VPC、子网和安全组**：Image Builder 将使用默认 VPC 和子网。有关配置 VPC 接口端点的更多信息，请参阅 [Image Builder 和 AWS PrivateLink 接口 VPC 终端节点](vpc-interface-endpoints.md)。
+ 在**故障排除设置**部分，配置以下值：
+ 默认情况下，**失败时终止实例**复选框为选中状态。但是，构建失败时，您可以登录 EC2 实例排查问题。如果您希望实例在构建失败后继续运行，请清除该复选框。
+ **密钥对**：如果 EC2 实例在构建失败后继续运行，则可以创建密钥对或使用现有密钥对登录实例并排查问题。
+ **日志**：您可以指定一个 S3 存储桶，Image Builder 可以在其中写入应用程序日志，以帮助构建和测试排查问题。如果您未指定 S3 存储桶，Image Builder 会将应用程序日志写入实例。
+ 在**实例元数据设置**部分，您可以配置以下值以应用于 Image Builder 用于构建和测试映像的 EC2 实例：
+ 选择**元数据版本**，确定 EC2 是否要求为元数据检索请求提供签名令牌标头。
+ **V1 和 V2（令牌可选）**：如果您未选择任何内容，则为默认值。
+ **V2（令牌必填）**
**注意**
我们建议您将 Image Builder 从管道构建中启动的所有 EC2 实例配置为使用， IMDSv2 以便实例元数据检索请求需要签名的令牌标头。
+ **元数据标记响应跃点限制** – 元数据令牌可以传输的网络跃点数。最小跃点数：1，最大跃点数：64，默认为一跃点。
+ 在**实例放置设置**部分，您可以配置以下值以应用于 Image Builder 用于构建和测试映像的 EC2 实例：
+ 您可以选择 Image Builder 在创建映像期间启动实例的**可用区**。
+ （可选）为运行您启动的实例的服务器选择**租赁**。默认情况下，EC2 实例将在共享租赁硬件上运行。这表示多个 AWS 账户 可能会共享相同物理硬件。具有 `dedicated` 租期的实例在单租户硬件上运行。具有 `host` 租期的实例在专属主机上运行。
在构建自定义映像之前，Mac 实例需要一台作为先决条件创建的专属主机。为您的 macOS 映像选择 `host`。然后，您可以选择目标主机或主机资源组来启动实例，但如果您的专属主机启用了自动置放功能，则不需要这样做。有关更多信息，请参阅《Amazon EC2 用户指南》中的[自动置放](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/dedicated-hosts-understanding.html#dedicated-hosts-auto-placement)。
+ **租赁主机 ID** - 运行实例的专属主机的 ID。
+ **租赁主机资源组** - 要在其中启动实例的主机资源组的 Amazon 资源名称 (ARN)。
1. 在**基础设施标签**部分（可选）中，您可以将元数据标签分配给 Image Builder 在构建过程中启动的 Amazon EC2 实例。输入标签作为键值对。
1. 在**标签**部分（可选）中，您可以将元数据标签分配给 Image Builder 作为输出创建的基础设施配置资源。输入标签作为键值对。
------
#### [ AWS CLI ]
以下步骤说明如何使用 AWS CLI中的 Image Builder **[create-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-infrastructure-configuration.html)** 命令为您的映像配置基础设施。步骤 2 中的命令采用您在步骤 1 中创建的文件。对于这些示例，步骤 1 中的文件称为 `create-infrastructure-configuration.json`。
1.
**创建 CLI 输入 JSON 文件**
以下示例展示了您可能为基础设施配置创建的 JSON 文件的变体。使用文件编辑工具创建您自己的 JSON 文件。
**示例 1：用于保留编译失败后的实例的配置**
此示例指定了两种实例类型，即 `m5.large` 和 `m5.xlarge`。我们建议指定多种实例类型，因为这允许 Image Builder 从具有足够容量的池中启动实例。这可以减少临时的生成失败次数。
`instanceProfileName` 规定了实例配置文件，该文件用于为实例提供执行自定义活动所需的权限。例如，如果您具有一个从 Amazon S3 中检索资源的组件，则实例配置文件需要具有访问这些文件的权限。该实例配置文件还需要具备能使EC2 Image Builder 成功与实例进行通信的最低权限。有关更多信息，请参阅 [准备好使用 Image Builder 构建自定义映像](set-up-ib-env.md)。
```
{
"name": "ExampleInfraConfigDontTerminate",
"description": "An example that will retain instances of failed builds",
"instanceTypes": [
"m5.large", "m5.xlarge"
],
"instanceProfileName": "myIAMInstanceProfileName",
"securityGroupIds": [
"sg-12345678"
],
"subnetId": "sub-12345678",
"logging": {
"s3Logs": {
"s3BucketName": "my-logging-bucket",
"s3KeyPrefix": "my-path"
}
},
"keyPair": "myKeyPairName",
"terminateInstanceOnFailure": false,
"snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic"
}
```
**示例 2：具有自动置放功能的 macOS 配置**
此示例为专属主机启用了自动置放功能的 Mac 实例指定实例类型和置放位置。
```
{
"name": "macOSInfraConfigAutoPlacement",
"description": "An example infrastructure configuration for macOS.",
"instanceProfileName": "EC2InstanceProfileForImageBuilder",
"instanceTypes": ["mac1.metal, mac2.metal"],
"terminateInstanceOnFailure": false,
"placement": {
"tenancy": "host"
}
}
```
**示例 3：指定了主机 ID 的 macOS 配置**
此示例为以特定专属主机为目标的 Mac 实例指定实例类型和置放位置。
```
{
"name": "macOSInfraConfigHostPlacement",
"description": "An example infrastructure configuration for macOS.",
"instanceProfileName": "EC2InstanceProfileForImageBuilder",
"instanceTypes": ["mac2-m1ultra.metal"],
"terminateInstanceOnFailure": false,
"placement": {
"tenancy": "host",
"hostId" : "h-1234567890abcdef0"
}
}
```
1.
**当您运行以下命令时，使用您作为输入而创建的文件。**
```
aws imagebuilder create-infrastructure-configuration --cli-input-json file://create-infrastructure-configuration.json
```
------
# 更新基础设施配置
本节介绍如何使用 Image Builder 控制台或中的**imagebuilder**命令 AWS CLI 来更新基础设施配置资源。要跟踪资源，可以应用标签，如下所示。输入标签作为键值对。
+ *资源标签*将元数据标签分配给 Image Builder 在构建过程中启动的 Amazon EC2 实例。
+ *标签*将元数据标签分配给 Image Builder 作为输出创建的基础设施配置资源。
------
#### [ Console ]
您可以从 Image Builder 控制台编辑以下基础设施配置详细信息：
+ 基础设施配置的**描述**。
+ 将 **IAM 角色** 与实例配置文件关联。
+ **AWS 基础架构**，包括**实例类型**和通知的 **SNS 主题**。
+ **VPC、子网和安全组**。
+ **问题排查设置**（包括**失败时终止实例**、用于连接的**密钥对**以及用于存储实例日志的可选 S3 存储桶位置）。
要通过 Image Builder 控制台更新基础设施配置资源，请执行以下步骤：
**配置选择现有的 Image Builder 基础设施配置**
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 要查看您账户下的基础设施配置资源列表，请从导航窗格中选择**基础设施配置**。
1. 要查看详细信息或编辑基础设施配置，请选择**配置名称**链接。此操作将打开基础设施配置的详细视图。
**注意**
您也可以选中**配置名称**旁边的框，然后选择**查看详细信息**。
1. 在**基础设施详细信息**面板的右上角，选择**编辑**。
1. 准备保存对基础设施配置所做的更新时，请选择**保存更改**。
------
#### [ AWS CLI ]
以下示例展示了如何使用 AWS CLI中的 Image Builder **[update-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-infrastructure-configuration.html)** 命令更新映像的基础设施配置。
1.
**创建 CLI 输入 JSON 文件**
此基础设施配置示例使用的设置与创建示例相同，仅仅将 `terminateInstanceOnFailure` 设置更新为 `false`。运行 **update-infrastructure-configuration** 命令后，使用此基础设施配置的管道将在构建失败时终止构建和测试实例。
使用文件编辑工具创建一个 JSON 文件，其中包含以下示例中显示的密钥，以及对您的环境有效的值。此示例使用名为 `update-infrastructure-configuration.json` 的文件：
```
{
"infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration",
"description": "An example that will terminate instances of failed builds",
"instanceTypes": [
"m5.large", "m5.2xlarge"
],
"instanceProfileName": "myIAMInstanceProfileName",
"securityGroupIds": [
"sg-12345678"
],
"subnetId": "sub-12345678",
"logging": {
"s3Logs": {
"s3BucketName": "my-logging-bucket",
"s3KeyPrefix": "my-path"
}
},
"terminateInstanceOnFailure": true,
"snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic"
}
```
1.
**当您运行以下命令时，使用您作为输入而创建的文件。**
```
aws imagebuilder update-infrastructure-configuration --cli-input-json file://update-infrastructure-configuration.json
```
------
# Image Builder 和 AWS PrivateLink 接口 VPC 终端节点
您可以通过创建*接口 VPC 端点*在 VPC 和 EC2 Image Builder 之间建立私有连接。接口端点由一项技术提供支持 [AWS PrivateLink](https://aws.amazon.com/privatelink/)，该技术使您 APIs 无需互联网网关、NAT 设备、VPN 连接或 Direct Connect 连接即可私密访问 Image Builder。您的 VPC 中的实例不需要公有 IP 地址即可与 Image Builder 通信 APIs。VPC 和 Image Builder 之间的流量不会脱离 Amazon 网络。
每个接口端点均由子网中的一个或多个[弹性网络接口](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)表示。创建新映像时，可以在基础设施配置中指定 VPC 子网 ID。
**注意**
您从 VPC 内访问的每项服务都有自己的接口端点和自己的端点策略。Image Builder 下载 AWSTOE 组件管理器应用程序并访问 S3 存储桶中的托管资源以创建自定义映像。要授予访问这些存储桶的权限，您必须更新 S3 端点策略以允许访问。有关更多信息，请参阅 [访问 S3 存储桶的自定义策略](#vpc-endpoint-policy-s3)。
有关 VPC 端点的更多信息，请参阅 *Amazon VPC 用户指南*中的[接口 VPC 端点 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html)。
## Image Builder VPC 端点的注意事项
请务必先查看 *Amazon VPC 用户指南*中的[接口端点属性和限制](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#vpce-interface-limitations)，然后再为 Image Builder 设置接口 VPC 端点。
Image Builder 支持从 VPC 调用它的所有 API 操作。
## 为 Image Builder 创建接口 VPC 端点
要为 Image Builder 服务创建 VPC 终端节点，您可以使用亚马逊 VPC 控制台或 AWS Command Line Interface (AWS CLI)。有关更多信息，请参阅《Amazon VPC User Guide》**中的 [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint)。
使用以下服务名称为 Image Builder 创建 VPC 端点：
+ com.amazonaws。 *region*.imagebuilder
如果为终端节点启用私有 DNS，则可以使用其默认 DNS 名称作为区域，向 Image Builder 发送 API 请求，例如：`imagebuilder.us-east-1.amazonaws.com`。要查找适用于您的目标区域的端点，请参阅 [*Amazon Web Services 一般参考* 中的 EC2 Image Builder 端点和配额](https://docs.aws.amazon.com/general/latest/gr/imagebuilder.html#imagebuilder_region)。
有关更多信息，请参阅《Amazon VPC 用户指南》**中的[通过接口端点访问服务](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#access-service-though-endpoint)。
## 为 Image Builder 创建 VPC 端点策略
您可以为 VPC 端点附加控制对 Image Builder 的访问的端点策略。该策略指定以下信息：
+ 可执行操作的主体。
+ 可执行的操作。
+ 可对其执行操作的资源。
如果您在配方中使用 Amazon 托管的组件，则 Image Builder 的 VPC 端点必须允许访问以下服务拥有的组件库：
`arn:aws:imagebuilder:region:aws:component/*`
**重要**
将非默认策略应用于 EC2 Image Builder 的接口 VPC 终端节点时，某些失败的 API 请求（例如失败的请求）可能不会记录到 AWS CloudTrail 或 Amazon CloudWatch。`RequestLimitExceeded`
有关更多信息，请参阅《Amazon VPC User Guide》**中的 [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)。
### 访问 S3 存储桶的自定义策略
Image Builder 使用公开可用的 S3 存储桶来存储和访问托管的资源，例如组件。它还会从单独的 S3 存储桶下载 AWSTOE 组件管理应用程序。如果您在环境中使用 Amazon S3 的 VPC 端点，则需要确保您的 S3 VPC 端点策略允许 Image Builder 访问以下 S3 存储桶。每个 AWS 区域 (*region*) 和应用程序环境 (*environment*) 的存储桶名称都是唯一的。Image Builder 并 AWSTOE 支持以下应用程序环境：`prod``preprod`、和`beta`。
+ AWSTOE 组件管理器存储桶：
```
s3://ec2imagebuilder-toe-region-environment
```
**示例：**s3://ec2 imagebuilder-toe-us-west -2-prod/\$1
+ Image Builder 托管资源存储桶：
```
s3://ec2imagebuilder-managed-resources-region-environment/components
```
**示例：**s3://ec2 imagebuilder-managed-resources-us-west-2-prod/components/\$1
### VPC 端点策略示例
本节包括自定义 VPC 端点策略的示例。
**Image Builder 操作的常规 VPC 端点策略**
以下是拒绝删除 Image Builder 映像和组件的权限的 Image Builder 终端节点策略示例。示例策略还授予执行所有其他 EC2 Image Builder 操作的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "imagebuilder:*",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": "imagebuilder:DeleteImage",
"Effect": "Deny",
"Resource": "*"
},
{
"Action": "imagebuilder:DeleteComponent",
"Effect": "Deny",
"Resource": "*"
}
]
}
```
------
**按组织限制访问权限，允许访问托管组件**
以下端点策略示例说明了如何对属于您组织的身份和资源的访问权限进行限制，以及如何提供对 Amazon 托管的 Image Builder 组件的访问权限。将*region**principal-org-id*、和，替换*resource-org-id*为贵组织的价值观。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": "principal-org-id",
"aws:ResourceOrgID": "resource-org-id"
}
}
},
{
"Sid": "AllowAccessToEC2ImageBuilderComponents",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"imagebuilder:GetComponent"
],
"Resource": [
"arn:aws:imagebuilder:us-east-1:aws:component/*"
]
}
]
}
```
------
**访问 Amazon S3 存储桶的 VPC 端点策略**
以下 S3 端点策略示例显示了如何提供对 Image Builder 用于构建自定义映像的 S3 存储桶的访问权限。*environment*用贵组织的价值观替换*region*和。根据您的应用程序要求向策略添加任何其他必需的权限。
**注意**
对于 Linux 映像，如果您未在映像配方中指定用户数据，Image Builder 会添加一个脚本，用于在映像的构建和测试实例上下载和安装 Systems Manager Agent。要下载代理，Image Builder 会访问您的构建区域的 S3 存储桶。
为确保 Image Builder 可以引导构建和测试实例，请在 S3 端点策略中添加以下额外资源：
"`arn:aws:s3:::amazon-ssm-region/*`"
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowImageBuilderAccessToAppAndComponentBuckets",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::ec2imagebuilder-toe-region-environment/*",
"arn:aws:s3:::ec2imagebuilder-managed-resources-region-environment/components/*"
]
}
]
}
```
------
# 管理 Image Builder 分配设置
在为输出映像配置分配设置之前，我们建议您针对在分配目标区域中从您的输出映像启动的实例，验证所有底层基础设施的可用性或其他要求。例如，并非所有区域都支持 EC2 Mac 专属主机，而这些主机对于从 macOS 映像启动实例是必需的。有关专属主机的实例类型和定价的更多信息，请参阅 [Amazon EC2 专属主机定价](https://aws.amazon.com/ec2/dedicated-hosts/pricing/)。
使用 Image Builder 创建分配设置后，您可以使用 Image Builder 控制台、Image Builder API 或 AWS CLI中的 **imagebuilder** 命令对其进行管理。通过使用分配设置，您可以执行以下操作：
**AMI 分配**
+ 指定输出 AMI 的名称和描述。
+ 授权其他组织 AWS 账户、组织以及 OUs 从所有者的账户启动 AMI。所有者账户需要支付与 AMI 相关的费用。
**注意**
要公开 AMI，请将启动许可授权账户设置为 `all`。有关相关信息和示例，请参阅《Amazon EC2 API 参考》**中的 **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)**。
+ 为每个指定的目标账户、组织和目标区域创建输出 AMI OUs 的副本。目标账户、组织和 OUs 拥有自己的 AMI 副本，并需支付任何相关费用。有关向 AWS Organizations 和分发 AMI 的更多信息 OUs，请参阅[与组织共享 AMI 或 OUs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html)。
+ 将 AMI 复制到其他所有者的账户 AWS 区域。
+ 将 VM 映像磁盘导出到 Amazon Simple Storage Service (Amazon S3)。有关更多信息，请参阅 [示例：为来自的输出 VM 磁盘创建分发设置 AWS CLI](cr-upd-ami-distribution-settings.md#cli-create-vm-dist-config)。
**容器映像分配**
+ 指定 Image Builder 在分配区域中存储输出映像的 ECR 存储库。
您可以通过以下方式使用分发设置，将图像一次性传送到目标区域、账户 AWS Organizations 和组织单位 (OUs)，或者每次构建管道：
+ 要自动将更新的图像传送到指定的区域、账户、Organizations 和 OUs，请将分发设置与按计划运行的 Image Builder 管道配合使用。
+ 要创建新映像并将其交付给指定的区域、账户、组织和，请使用 “**操作**” 菜单中的 “运行管道” OUs，将分发设置与 Image Builder 管道一起使用，该**管道从图像生成器控制台运行**一次。
+ 要创建新映像并将其交付给指定的区域、账户、组织和，请使用分发设置以及 OUs以下 API 操作或 Image Builder 命令 AWS CLI：
+ Image Builder API 中的 **[CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html)** 操作。
+ AWS CLI中的 **[create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html)** 命令。
+ 作为常规映像构建过程的一部分，将虚拟机 (VM) 映像磁盘导出到目标区域的 S3 存储桶。
**提示**
在您具有相同类型的许多资源时，标记可帮助您根据分配给特定资源的标签来识别它。有关使用 Image Builder 命令为资源添加标签的更多信息 AWS CLI，请参阅本指南的[标记资源](tag-resources.md)部分。
**Topics**
+ [
# 列出和查看分配配置详细信息
](distribution-settings-detail.md)
+ [
# 创建和更新 AMI 分配配置
](cr-upd-ami-distribution-settings.md)
+ [
# 创建和更新容器映像的分配设置
](cr-upd-container-distribution-settings.md)
+ [
# 使用 Image Builder 设置跨账户 AMI 分配
](cross-account-dist.md)
+ [
# 使用 EC2 启动模板配置 AMI 分配
](dist-using-launch-template.md)
+ [
# 使用增强的 AMI 分发功能
](distribution-enhanced_functionality.md)
# 列出和查看分配配置详细信息
本章节介绍查找 EC2 Image Builder 分配配置信息和查看详细信息的多种方法。
**Topics**
+ [
## 通过控制台列出分配配置
](#list-distribution-config-console)
+ [
## 通过控制台查看分配配置详细信息
](#view-distribution-config-details-console)
+ [
## 列出来自 AWS CLI
](#cli-list-distributions)
+ [
## 从中获取分发配置的详细信息 AWS CLI
](#cli-get-distribution-configuration)
## 通过控制台列出分配配置
要在 Image Builder 控制台中查看在您的帐户下创建的分配配置列表，请执行以下步骤：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**分配设置**。这将显示在您的账户下创建的分配配置的列表。
1. 要查看详细信息或创建新的分配配置，请选择**配置名称**链接。这将打开分配设置的详细视图。
**注意**
您也可以选中**配置名称**旁边的框，然后选择**查看详细信息**。
## 通过控制台查看分配配置详细信息
要使用 Image Builder 控制台查看特定分配配置的详细信息，请使用 [通过控制台列出分配配置](#list-distribution-config-console) 中描述的步骤选择要查看的配置。
在分配详情页面上，您可以：
+ **删除**分配配置。有关删除 Image Builder 中的资源的更多信息，请参阅 [删除过期或未使用的 Image Builder 资源](delete-resources.md)。
+ **编辑**分配的详细信息。
## 列出来自 AWS CLI
以下示例说明如何使用中的**[list-distribution-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-distribution-configurations.html)**命令列 AWS CLI 出所有发行版。
```
aws imagebuilder list-distribution-configurations
```
## 从中获取分发配置的详细信息 AWS CLI
以下示例说明如何使用中的**[get-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-distribution-configuration.html)**命令通过指定分配配置的 Amazon 资源名称 (ARN) 来获取分配配置的详细信息。 AWS CLI
```
aws imagebuilder get-distribution-configuration --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration
```
# 创建和更新 AMI 分配配置
本节介绍如何创建和更新 Image Builder AMI 的分配配置。
**Topics**
+ [
## AMI 分发先决条件
](#ami-distribution-config-prereqs)
+ [
## 创建 AMI 分发配置
](#create-ami-distribution-config)
+ [
## 更新 AMI 分发配置
](#update-ami-distribution-config)
+ [
## 示例：使用输出启动模板启用 EC2 快速启动 AMIs
](#create-ami-dist-win-fast-launch)
+ [
## 示例：为来自的输出 VM 磁盘创建分发设置 AWS CLI
](#cli-create-vm-dist-config)
## AMI 分发先决条件
某些分发设置有先决条件，如下所示：
**Topics**
+ [SSM 输出参数先决条件](#ami-distribution-prereqs-ssm-param)
+ [EC2 Fast Launch 先决条件](#ami-distribution-prereqs-fast-launch)
### SSM 输出参数的先决条件
在创建用于设置 AWS Systems Manager 参数存储参数（SSM 参数）的新 AMI 分发配置之前，请确保满足以下先决条件。
**执行角色**
在中创建管道或使用 create-image 命令时 AWS CLI，只能指定一个 Image Builder 执行角色。如果您定义了 Image Builder 工作流程执行角色，则需要向该角色添加任何其他功能权限。否则，您将创建一个包含所需权限的新自定义角色。
+ 要在分发期间将输出 AMI ID 存储在 SSM 参数中，您必须在 Image Builder 执行角色中指定`ssm:PutParameter`操作，并将该参数列为资源。
+ 当您将参数数据类型设置为`AWS EC2 Image`以向 Systems Manager 发出信号，要求其将参数值作为 AMI ID 进行验证时，还必须添加`ec2:DescribeImages`操作。
### EC2 快速启动的先决条件
在为适用于 Windows AMIs 的 EC2 Fast Launch 创建新的分配配置之前，请确保满足以下先决条件。
+ 如果在配置 EC2 Fast Launch 时提供了自定义启动模板，则该服务将使用您在启动模板中定义的 VPC 和其他配置设置。有关更多信息，请参阅[在设置 EC2 快速启动时使用启动模板](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-configure.html#win-fast-launch-with-template)。
+ 如果您不使用自定义启动模板来配置设置，则必须将[https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html)策略附加到 Image Builder 用于创建映像的 IAM 角色。在中创建管道或使用 create-image 命令时 AWS CLI，只能指定一个 Image Builder 执行角色。如果您定义了 Image Builder 工作流程执行角色，则需要向该角色添加任何其他功能权限。否则，您将创建一个包含所需权限的新自定义角色。
然后，当 Image Builder 复制您的映像时，EC2 Fast Launch 会自动创建一个 CloudFormation 堆栈，其中包含以下资源 AWS 账户。
+ 虚拟私有云（VPC）
+ 跨多个可用区的若干私有子网
+ 使用实例元数据服务版本 2 配置的启动模板 (IMDSv2)
+ 一个没有任何入站或出站规则的安全组
**注意**
对于预先启用 EC2 Fast Launch 的 AMI，Image Builder 不支持跨账户分配。必须从目标账户启用 EC2 Fast Launch。
## 创建 AMI 分发配置
分发配置包括输出 AMI 名称、用于加密的特定区域设置、启动权限以及可以启动输出 AMI 的组织和组织单位 (OUs) 以及许可证配置。 AWS 账户
分布配置允许您指定输出 AMI 的名称和描述，授权其他 AWS 账户 人启动 AMI，将 AMI 复制到其他账户，以及将 AMI 复制到其他 AWS 区域。它还允许你将 AMI 导出到亚马逊简单存储服务 (Amazon S3)，或者为输出 Windows 配置 EC2 快速启动。AMIs要公开 AMI，请将启动许可授权账户设置为 `all`。请参阅位于 EC2 **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)** 的公开 AMI 示例。
------
#### [ Console ]
按照以下步骤在中创建新的 AMI 分发配置 AWS 管理控制台：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**分配设置**。这将显示在您的账户下创建的分配配置的列表。
1. 选择**分配设置**面板顶部附近的**创建分配设置**。
1. 在**映像类型**部分，选择 **Amazon Machine Image (AMI)** 输出类型。
1. 在**常规**部分，输入分配配置的**名称**和可选描述。
1. 在**区域设置**部分，输入您要分配 AMI 的每个区域的以下详细信息：
1. 默认情况下，AMI 分配到当前区域（**区域 1**）。**区域 1** 是分配的来源。**区域 1** 的某些设置未开放编辑功能。对于您添加的任何区域，您可以从**区域**下拉列表中选择一个区域。
Kms **密钥**标 AWS KMS key 识用于加密目标区域中映像的 EBS 卷。请务必注意，这不适用于该构建在源区域（**区域 1**）中使用您的账户创建的原始 AMI。在该构建的分配阶段运行的加密仅适用于分配给其他账户或地区的映像。
要对在源区域为您的账户创建的 AMI 的 EBS 卷进行加密，您必须在映像配方块设备映射（控制台中的**存储（卷））**中设置 KMS 密钥。
Image Builder 将 AMI 复制到您为该区域指定的**目标账户**。
**先决条件**
要跨账户复制映像，您必须在所有分配目标账户中创建 `EC2ImageBuilderDistributionCrossAccountRole` 角色，并将 [Ec2ImageBuilderCrossAccountDistributionAccess 策略](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) 托管策略附加到该角色。
**输出 AMI 名称**为可选项。如果您提供了名称，则最终的输出 AMI 名称会附加一个 AMI 构建时间的时间戳。如果未指定名称，Image Builder 会将构建时间戳附加到配方名称。这样可以确保每次构建的 AMI 名称都是唯一的。
1. 通过 AMI 共享，您可以向指定的 AWS 委托人授予从您的 AMI 启动实例的访问权限。如果展开 **AMI 共享**部分，则可以输入以下详细信息：
+ **启动权限** — 如果您想保持 AMI **私**有，请选择私有，并允许特定 AWS 委托人访问您的私有 AMI 启动实例。如果要使 AMI 公开，请选择**公开**。任何 AWS 委托人都可以从您的公有 AMI 启动实例。
+ **委托人**-您可以为以下类型的 AWS 委托人授予启动实例的访问权限：
+ **AWS 账户**-授予对特定 AWS 账户的访问权限
+ **组织单位 (OU)** — 授予对 OU 及其所有子实体的访问权限。子实体包括 OUs 和 AWS 帐户。
+ **组织**-授予您 AWS Organizations及其所有子实体的访问权限。子实体包括 OUs 和 AWS 帐户。
首先，选择主体类型。然后在下拉列表右侧的框中，输入要授予访问权限的 AWS 主体的 ID。您可以输入 IDs 多种不同的类型。
1. 您可以展开 “**许可配置**” 部分，将使用创建的许可配置附加 AWS License Manager 到 Image Builder 映像。许可证配置包含基于您的企业协议条款的许可规则。Image Builder 会自动包含与您的基本 AMI 关联的许可证配置。
1. 您可以展开**启动模板配置**部分，指定用于从您创建的 AMI 启动实例的 EC2 启动模板。
如果您使用的是 EC2 启动模板，则可以指示 Image Builder 在构建完成后创建包含最新 AMI ID 的启动模板的新版本。要更新启动模板，请按以下方式配置设置：
+ **启动模板名称** — 选择您希望 Image Builder 更新的启动模板的名称。
+ **设置默认版本** — 选中此复选框可将启动模板的默认版本更新为新版本。
要添加另一个启动模板配置，请选择添加**启动模板配置**。您在每个区域最多可以拥有五种启动模板配置。
1. 您可以展开 **SSM 参数配置部分来配置** SSM 参数，该参数将存储分发到目标区域的图像的输出 AMI ID。您可以选择在该地区指定一个分销账户。
**参数名称**-输入参数的名称。例如 `/output/image/param`。
**数据类型**-保留默认值 (`AWS EC2 Image`)。这会让 Systems Manager 验证参数值以确保它是有效的 AMI ID。
1. 要为其他区域添加分配设置，请选择**添加区域**。
1. 完成后，选择**创建设置**。
------
#### [ AWS CLI ]
以下示例说明如何采用 AWS CLI使用 **create-distribution-configuration** 命令为 AMI 创建新的分配配置。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建一个 JSON 文件，其中包含以下示例之一中显示的密钥，以及对您的环境有效的值。这些示例定义了哪些 AWS 账户 AWS Organizations 或哪些组织单位 (OUs) 有权启动您分发到指定区域的 AMI。对文件 `create-ami-distribution-configuration.json` 进行命名，以便在下一步中使用：
**示例 1：分发到 AWS 账户**
此示例将 AMI 分配到两个区域，并指定在每个区域都拥有启动权限的 AWS 账户 。
```
{
"name": "MyExampleAccountDistribution",
"description": "Copies AMI to eu-west-1, and specifies accounts that can launch instances in each Region.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "An example image name with parameter references",
"amiTags": {
"KeyName": "Some Value"
},
"launchPermission": {
"userIds": [
"987654321012"
]
}
}
},
{
"region": "eu-west-1",
"amiDistributionConfiguration": {
"name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}",
"amiTags": {
"KeyName": "Some value"
},
"launchPermission": {
"userIds": [
"100000000001"
]
}
}
}
]
}
```
**示例 2：分发给 Organiations 和 OUs**
此示例将 AMI 分配到源区域，并指定组织和 OU 启动权限。
```
{
"name": "MyExampleAWSOrganizationDistribution",
"description": "Shares AMI with the Organization and OU",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{ imagebuilder:buildDate }}",
"launchPermission": {
"organizationArns": [
"arn:aws:organizations::123456789012:organization/o-myorganization123"
],
"organizationalUnitArns": [
"arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit"
]
}
}
}
]
}
```
**示例 3：将输出的 AMI ID 存储在 SSM 参数中**
此示例将输出 AMI ID 存储在分布区域的 AWS Systems Manager 参数存储参数中。
```
{
"name": "SSMParameterOutputAMI",
"description": "Updates an SSM parameter with the output AMI ID for the distribution.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{ imagebuilder:buildDate }}"
},
"ssmParameterConfigurations": [
{
"amiAccountId": "111122223333",
"parameterName": "/output/image/param",
"dataType": "aws:ec2:image"
}
]
}
]
}
```
1.
**使用创建的文件作为输入，运行以下命令。**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://create-ami-distribution-configuration.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)**。
------
## 更新 AMI 分发配置
您可以更改 AMI 分发配置。但是，所做的更改不适用于 Image Builder 已经分配的任何资源。例如，如果您已将 AMI 分配到某个区域，但随后又将其从分配中移除，则在您手动将其移除之前，已分配的 AMI 将保留在该区域中。
------
#### [ AWS 管理控制台 ]
按照以下步骤进行 AMI 分发配置 AWS 管理控制台：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**分配设置**。这将显示在您的账户下创建的分配配置的列表。
1. 要查看详细信息或更新分配配置，请选择**配置名称**链接。这将打开分配设置的详细视图。
**注意**
您也可以选中**配置名称**旁边的框，然后选择**查看详细信息**。
1. 要编辑分配配置，请从**分配详细信息**部分的右上角选择**编辑**。某些字段已锁定，例如分配配置的**名称**和显示为**区域 1** 的默认**区域**。有关分配配置设置的更多信息，请参阅 [创建 AMI 分发配置](#create-ami-distribution-config)。
1. 完成后，选择 **Save changes**（保存更改）。
------
#### [ AWS CLI ]
以下示例说明如何通过 AWS CLI使用 **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** 命令为您的 AMI 更新分配配置。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建 JSON 文件，其中包含以下示例中显示的密钥以及对您的环境有效的值。此示例使用名为 `update-ami-distribution-configuration.json` 的文件。
```
{
"distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration.json",
"description": "Copies AMI to eu-west-2, and specifies accounts that can launch instances in each Region.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "An example image name with parameter references",
"launchPermissions": {
"userIds": [
"987654321012"
]
}
}
},
{
"region": "eu-west-2",
"amiDistributionConfiguration": {
"name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}",
"tags": {
"KeyName": "Some value"
},
"launchPermissions": {
"userIds": [
"100000000001"
]
}
}
}
]
}
```
1.
**使用创建的文件作为输入，运行以下命令。**
```
aws imagebuilder update-distribution-configuration --cli-input-json file://update-ami-distribution-configuration.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)**。要更新分配配置资源的标签，请参阅 [标记资源](tag-resources.md) 一节。
------
## 示例：使用输出启动模板启用 EC2 快速启动 AMIs
以下示例说明如何使用带有启动模板的**[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)**命令来创建分配设置，这些设置已为您的 AMI 配置了 EC2 快速启动，请从中获得 AWS CLI。
要在没有启动模板的情况下配置 EC2 Fast Launch 设置，请确保[EC2 Fast Launch 先决条件](#ami-distribution-prereqs-fast-launch)在创建分配配置之前满足所有要求。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建一个 JSON 文件，其中包含以下示例中显示的密钥，以及对您的环境有效的值。
此示例同时启动其所有目标资源的实例，因为并行启动的最大数量大于目标资源数量。该文件在下一步所示的命令示例中被命名为 `ami-dist-config-win-fast-launch.json`。
```
{
"name": "WinFastLaunchDistribution",
"description": "An example of Windows AMI EC2 Fast Launch settings in the distribution configuration.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "Includes Windows AMI EC2 Fast Launch settings.",
"amiTags": {
"KeyName": "Some Value"
}
},
"fastLaunchConfigurations": [{
"enabled": true,
"snapshotConfiguration": {
"targetResourceCount": 5
},
"maxParallelLaunches": 6,
"launchTemplate": {
"launchTemplateId": "lt-0ab1234c56d789012",
"launchTemplateVersion": "1"
}
}],
"launchTemplateConfigurations": [{
"launchTemplateId": "lt-0ab1234c56d789012",
"setDefaultVersion": true
}]
}]
}
```
**注意**
您可以指定 `launchTemplateName` 而非 `launchTemplate` 部分中的 `launchTemplateId`，但不能同时指定名称和 ID。
1.
**使用创建的文件作为输入，运行以下命令。**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://ami-dist-config-win-fast-launch.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)**。
## 示例：为来自的输出 VM 磁盘创建分发设置 AWS CLI
以下示例说明如何使用 **create-distribution-configuration** 命令创建分配设置，以便在每次构建映像时将 VM 映像磁盘导出到 Amazon S3。
1.
**创建 CLI 输入 JSON 文件**
您可以简化在 AWS CLI中使用的 **create-distribution-configuration** 命令。为此，请创建一个 JSON 文件，其中包含要传递到命令中的所有导出配置。
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 操作请求参数，请参阅《*EC2 Image Builder API 参考*》中的**[CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)**命令。
要将数据值作为命令行参数提供，请参阅 *AWS CLI 命令参考*中指定的参数名，将 **create-distribution-configuration** 命令作为选项。
以下是我们在本示例的 `s3ExportConfiguration` JSON 对象中指定的参数摘要：
+ **RoleName**（字符串，必填）-向虚拟机授予将图像导出到 S3 存储桶的 Import/Export 权限的角色名称。
+ **diskImageFormat**（字符串，必填）-将更新的磁盘映像导出为以下支持的格式之一：
+ **虚拟硬盘 (VHD)**— 可与 Citrix Xen 和 Microsoft Hyper-V 虚拟化产品兼容。
+ **流优化的 ESX 虚拟机磁盘 (VMDK)** — 兼容 ESX VMware 和 VMware vSphere 版本 4、5 和 6。
+ **原始** — 原始格式。
+ **s3Bucket**（字符串，必填）— 用于存储 VM 的输出磁盘映像的 S3 存储桶。
将该文件保存为 `export-vm-disks.json`。在 **create-distribution-configuration** 命令中使用文件名。
```
{
"name": "example-distribution-configuration-with-vm-export",
"description": "example",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"description": "example-with-vm-export"
},
"s3ExportConfiguration": {
"roleName": "vmimport",
"diskImageFormat": "RAW",
"s3Bucket": "vm-bucket-export"
}
}],
"clientToken": "abc123def4567ab"
}
```
1.
**使用创建的文件作为输入，运行以下命令。**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://export-vm-disks.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)**。
# 创建和更新容器映像的分配设置
本章节介绍如何创建和更新 Image Builder 容器映像的分配设置。
**Topics**
+ [
## 从 Image Builder 容器映像创建分发设置 AWS CLI
](#cli-create-container-distribution-configuration)
+ [
## 从中更新容器映像的分发设置 AWS CLI
](#cli-update-container-distribution-configuration)
## 从 Image Builder 容器映像创建分发设置 AWS CLI
分发配置使您可以指定输出容器映像的名称和描述，并将容器映像复制到其他 AWS 区域。您也可以对分配配置资源和每个区域内的容器映像应用单独的标签。
1.
**创建 CLI 输入 JSON 文件**
使用您常用的文件编辑工具创建一个 JSON 文件，其中包含以下示例中显示的密钥，以及对您的环境有效的值。此示例使用名为 `create-container-distribution-configuration.json` 的文件：
```
{
"name": "distribution-configuration-name",
"description": "Distributes container image to Amazon ECR repository in two regions.",
"distributions": [
{
"region": "us-west-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["west2", "image1"]
}
},
{
"region": "us-east-1",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["east1", "imagedist"]
}
}
],
"tags": {
"DistributionConfigurationTestTagKey1": "DistributionConfigurationTestTagValue1",
"DistributionConfigurationTestTagKey2": "DistributionConfigurationTestTagValue2"
}
}
```
1.
**使用创建的文件作为输入，运行以下命令。**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://create-container-distribution-configuration.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)**。
## 从中更新容器映像的分发设置 AWS CLI
以下示例说明如何采用 AWS CLI使用 **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** 命令为容器映像创建新的分配配置。您还可以在每个区域内更新容器映像的标签。
1.
**创建 CLI 输入 JSON 文件**
使用您常用的文件编辑工具创建一个 JSON 文件，其中包含以下示例所示的密钥以及对您的环境有效的值。此示例使用名为 `update-container-distribution-configuration.json` 的文件：
```
{
"distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-container-distribution-configuration.json",
"description": "Distributes container image to Amazon ECR repository in two regions.",
"distributions": [
{
"region": "us-west-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["west2", "image1"]
}
},
{
"region": "us-east-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["east2", "imagedist"]
}
}
]
}
```
1.
**使用创建的文件作为输入，运行以下命令：**
```
aws imagebuilder update-distribution-configuration --cli-input-json file://update-container-distribution-configuration.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
有关更多详细信息，请参阅 *AWS CLI 命令参考*中的 **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)**。要更新分配配置资源的标签，请参阅 [标记资源](tag-resources.md) 一节。
# 使用 Image Builder 设置跨账户 AMI 分配
本部分介绍了如何配置分配设置，以将 Image Builder AMI 传递给您指定的其他账户。
然后，目标账户可以根据需要启动或修改 AMI。
**注意**
AWS CLI 本节中的命令示例假设您之前创建了图像配方和基础设施配置 JSON 文件。要为映像配方创建 JSON 文件，请参阅 [使用创建图像配方 AWS CLI](create-image-recipes.md#create-image-recipe-cli)。要为基础设施配置创建 JSON 文件，请参阅 [创建基础设施配置](create-infra-config.md)。
## 跨账户 AMI 分配的先决条件
为确保目标账户能够成功地从您的 Image Builder 映像启动实例，您必须为所有区域的所有目标账户配置相应权限。
如果您使用 AWS Key Management Service (AWS KMS) 加密您的 AMI，则必须 AWS KMS key 为您的账户配置一个用于加密新映像的。
当 Image Builder 执行跨账户分发加密操作时 AMIs，源账户中的图像将被解密并推送到目标区域，然后使用该区域的指定密钥对其进行重新加密。由于 Image Builder 代表目标账户行事，并使用您在目标区域创建的 IAM 角色，因此该账户必须有权访问源区域和目标区域中的密钥。
### 加密密钥
如果您的映像使用 AWS KMS加密，则需要满足以下先决条件。IAM 先决条件将在下一部分中介绍。
**源账户要求**
+ 在您构建和分配 AMI 的所有区域的账户中创建 KMS 密钥。您也可以使用现有密钥。
+ 更新所有这些密钥的密钥策略，以允许目标账户使用您的密钥。
**目标账户要求**
+ 向 `EC2ImageBuilderDistributionCrossAccountRole` 添加内联策略，允许该角色执行分配加密 AMI 所需的操作。有关 IAM 配置步骤，请参阅 [IAM 策略](#cross-account-prereqs-iam) 先决条件部分。
有关使用跨账户访问的更多信息 AWS KMS，请参阅*AWS Key Management Service 开发者指南*[中的允许其他账户中的用户使用 KMS 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html)。
在映像配方中指定您的加密密钥，如下所示：
+ 如果您使用的是 Image Builder 控制台，请从配方的**存储（卷）**部分的**加密（KMS 别名）**下拉列表中选择您的加密密钥。
+ 如果您使用的是 **CreateImageRecipe** API 操作或中的**create-image-recipe**命令，请在 AWS CLI JSON 输入下方的`ebs`部分`blockDeviceMappings`中配置您的密钥。
以下 JSON 片段显示了映像配方的加密设置。除了提供您的加密密钥外，您还必须将 `encrypted` 标志设置为 `true`。
```
{
...
"blockDeviceMappings": [
{
"deviceName": "Example root volume",
"ebs": {
"deleteOnTermination": true,
"encrypted": true,
"iops": 100,
"kmsKeyId": "image-owner-key-id",
...
},
...
}],
...
}
```
### IAM 策略
要在 AWS Identity and Access Management (IAM) 中配置跨账户分配权限，请执行以下步骤：
1. 要使用跨账户分布 AMIs 的 Image Builder，目标账户所有者必须在其账户中创建一个名为的新 IAM 角色`EC2ImageBuilderDistributionCrossAccountRole`。
1. 他们必须将 [Ec2ImageBuilderCrossAccountDistributionAccess 策略](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) 附加到角色才能启用跨账户分配。有关托管策略的更多信息，请参阅 *AWS Identity and Access Management 用户指南* 中的[托管策略与内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
1. 确认源账户 ID 已添加到目标账户的 IAM 角色所附的信任策略中。以下示例显示了目标账户中的信任策略，该策略指定了源账户的账户 ID。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:root"
},
"Action": "sts:AssumeRole"
}]
}
```
------
有关信任策略的更多信息，请参阅 *AWS Identity and Access Management 用户指南* 中的 [基于资源的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_resource-based)。
1. 如果您分配的 AMI 已加密，则目标账户所有者必须在其账户的 `EC2ImageBuilderDistributionCrossAccountRole` 中添加以下内联策略，以便使用您的 KMS 密钥。`Principal` 部分包含他们的账号。这使得 Image Builder 能够在使用每个 AWS KMS 区域的相应密钥对 AMI 进行加密和解密时代表他们采取行动。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowRoleToPerformKMSOperationsOnBehalfOfTheDestinationAccount",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey",
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"
],
"Resource": "*"
}
]
}
```
------
有关内联策略的更多信息，请参阅 *AWS Identity and Access Management 用户指南*中的[内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies)。
1. 如果您使用 `launchTemplateConfigurations` 指定 Amazon EC2 启动模板，则还必须在每个目标账户的 `EC2ImageBuilderDistributionCrossAccountRole` 中添加以下策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateLaunchTemplateVersion",
"ec2:ModifyLaunchTemplate"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/CreatedBy": "EC2 Image Builder"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeLaunchTemplates"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:launch-template/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/CreatedBy": "EC2 Image Builder"
}
}
}
]
}
```
------
1. 如果您使用 P AWS Systems Manager arameter Store 参数来存储分配账户和区域的输出 AMI 的 AMI ID，则必须在每个目标账户`EC2ImageBuilderDistributionCrossAccountRole`中将以下策略添加到您的中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*"
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeImages"
],
"Resource": "*"
}
]
}
```
------
## 跨账户分配的限制
跨账户分配 Image Builder 映像时有一些限制：
+ 每个目标区域的目标账户仅限 50 个并发 AMI 副本。
+ 如果要将半虚拟化 (PV) 虚拟化 AMI 复制到另一个区域，则目标区域必须支持 PV 虚拟化 AMIs。有关更多信息，请参阅 [Linux AMI 虚拟化类型](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/virtualization_types.html)。
+ 您无法创建加密快照的未加密副本。如果您没有为 `KmsKeyId` 参数指定 AWS Key Management Service (AWS KMS) 客户托管密钥，Image Builder 将使用 Amazon Elastic Block Store (Amazon EBS) 的默认密钥。有关更多信息，请参阅 *Amazon Elastic Compute Cloud 用户指南* 中的 [Amazon EBS 加密](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)。
有关更多信息，请参阅 [CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)*EC2 Image Builder API 参考*中的。
## 通过控制台为 Image Builder AMI 配置跨账户分配
本节介绍如何 AMIs 使用创建和配置用于跨账户分发您的 Image Builder 的分发设置。 AWS 管理控制台配置跨账户分配需要特定的 IAM 权限。在继续操作之前，您必须完成本部分的 [跨账户 AMI 分配的先决条件](#cross-account-dist-prereqs)。
要在 Image Builder 控制台中创建分配，请执行以下步骤：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**分配设置**。这将显示在您的账户下创建的分配设置列表。
1. 在**分配设置**页面的顶部，选择**创建分配设置**。这将跳转到**创建分配设置**页面。
1. 在**映像类型**部分，选择 **Amazon Machine Image (AMI)** 作为**输出类型**。这是默认设置。
1. 在**常规**部分中，输入要创建的分配设置资源的**名称**（*必填*）。
1. 在**区域设置**部分，在选定区域的**目标账户**中输入您要向其分配 AMI 的 12 位账户 ID，然后按**输入**。这将检查格式是否正确，然后框的下方会显示您输入的账户 ID。重复该过程以添加更多帐户。
要删除您输入的账户，请选择账户 ID 右侧显示的 **X**。
输入每个区域的**输出 AMI 名称**。
1. 继续指定所需的任何其他设置，然后选择**创建设置**以创建新的分配设置资源。
## 从中为 Image Builder AMI 配置跨账户分发 AWS CLI
本节介绍如何配置分发设置文件以及如何使用中的**create-image**命令在账户之间构建和分发 Image Builder AMI。 AWS CLI
配置跨账户分配需要特定的 IAM 权限。在运行 **create-image** 命令之前，您必须完成本部分的 [跨账户 AMI 分配的先决条件](#cross-account-dist-prereqs)。
1.
**配置分配设置文件**
在使用中的**create-image**命令创建分发给其他账户的 Image Builder AMI 之前，必须创建一个在`AmiDistributionConfiguration`设置 IDs 中指定目标账户的 `DistributionConfiguration` JSON 结构。 AWS CLI 您必须在源区域中指定至少一个 `AmiDistributionConfiguration`。
以下名为 `create-distribution-configuration.json` 的示例文件显示了源区域中跨账户映像分配的配置。
```
{
"name": "cross-account-distribution-example",
"description": "Cross Account Distribution Configuration Example",
"distributions": [
{
"amiDistributionConfiguration": {
"targetAccountIds": ["123456789012", "987654321098"],
"name": "Name {{ imagebuilder:buildDate }}",
"description": "ImageCopy Ami Copy Configuration"
},
"region": "us-west-2"
}
]
}
```
1.
**创建分配设置**
要使用中的[create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html)命令创建 Image Builder 分发设置资源 AWS CLI，请在命令中提供以下参数：
+ 在 `--name` 参数中输入分配的名称。
+ 附加您在 `--cli-input-json` 参数中创建的分配配置 JSON 文件。
```
aws imagebuilder create-distribution-configuration --name my distribution name --cli-input-json file://create-distribution-configuration.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
*您也可以使用 `--distributions` 参数直接在命令中提供 JSON。*
# 使用 EC2 启动模板配置 AMI 分配
为了帮助确保 Image Builder AMI 在目标账户和区域中获得一致的启动体验，您可以使用 `launchTemplateConfigurations` 在分配设置中指定 Amazon EC2 启动模板。当分配过程中存在 `launchTemplateConfigurations` 时，Image Builder 会创建新版本的启动模板，其中包含模板中的所有原始设置以及来自构建的新 AMI ID。有关使用启动模板启动 EC2 实例的更多信息，请根据您的目标操作系统参阅下列链接之一。
+ [通过启动模板启动 Linux 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html)
+ [通过启动模板启动 Windows 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html)
**注意**
当您在映像中包含用于启用 Windows 快速启动的启动模板时，启动模板必须包含以下标签，这样 Image Builder 才能代表您启用 Windows 快速启动。
`CreatedBy: EC2 Image Builder`
## 通过控制台将 EC2 启动模板添加到 AMI 分配设置
要为您的输出 AMI 提供启动模板，请在控制台中执行以下步骤：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 从导航窗格中，选择**分配设置**。这将显示在您的账户下创建的分配设置列表。
1. 在**分配设置**页面的顶部，选择**创建分配设置**。这将打开**创建分配设置**页面。
1. 在**映像类型**部分，选择 **Amazon Machine Image (AMI)** **输出类型**。这是默认设置。
1. 在**常规**部分中，输入要创建的分配设置资源的**名称**（*必填*）。
1. 在**区域设置**部分，从列表中选择 EC2 启动模板的名称。如果您的账户中没有启动模板，请选择**创建新的启动模板**，这将在 **EC2 控制面板**中打开**启动模板**。
选中**设置默认版本**复选框，将启动模板的默认版本更新为 Image Builder 使用您的输出 AMI 创建的新版本。
要向所选区域添加其他启动模板，请选择**添加启动模板配置**。
要移除启动模板，请选择**移除**。
1. 继续指定所需的任何其他设置，然后选择**创建设置**以创建新的分配设置资源。
## 将 EC2 启动模板添加到 AMI 分发设置中 AWS CLI
本节介绍如何使用启动模板配置分配设置文件，以及如何使用 AWS CLI 中的 **create-image** 命令来构建和分配 Image Builder AMI 以及使用它的启动模板的新版本。
1.
**配置分配设置文件**
在使用启动模板创建 Image Builder AMI 之前 AWS CLI，必须先创建一个用于指定`launchTemplateConfigurations`设置的分发配置 JSON 结构。您必须在源区域中指定至少一个 `launchTemplateConfigurations` 条目。
以下名为 `create-distribution-config-launch-template.json` 的示例文件显示了在源区域中配置启动模板的几种可能场景。
```
{
"name": "NewDistributionConfiguration",
"description": "This is just a test",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "test-{{imagebuilder:buildDate}}-{{imagebuilder:buildVersion}}",
"description": "description"
},
"launchTemplateConfigurations": [
{
"launchTemplateId": "lt-0a1bcde2fgh34567",
"accountId": "935302948087",
"setDefaultVersion": true
},
{
"launchTemplateId": "lt-0aaa1bcde2ff3456"
},
{
"launchTemplateId": "lt-12345678901234567",
"accountId": "123456789012"
}
]
}
],
"clientToken": "clientToken1"
}
```
1.
**创建分配设置**
要使用中的[create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html)命令创建 Image Builder 分发设置资源 AWS CLI，请在命令中提供以下参数：
+ 在 `--name` 参数中输入分配的名称。
+ 附加您在 `--cli-input-json` 参数中创建的分配配置 JSON 文件。
```
aws imagebuilder create-distribution-configuration --name my distribution name--cli-input-json file://create-distribution-config-launch-template.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
*您也可以使用 `--distributions` 参数直接在命令中提供 JSON。*
# 使用增强的 AMI 分发功能
Image Builder 提供高级分发功能， AMIs 可让您灵活控制跨区域和账户的分布方式。这些功能将分发与构建过程分开，允许您按需分发现有图像，高效地从分发失败中恢复，并通过可自定义的工作流程实施受控的多阶段分发策略。
您可以在 Image Builder 中使用增强的 AMI 分发功能直接执行分发活动，而无需重新运行完整的映像构建。
## 解耦分布
DistributeImage API 接受三种类型的源图像引用：
+ **AMI ID** — 标准的 AMI 标识符（例如，`ami-0abcdef1234567890`）
+ **SSM 参数** — 存储 AMI ID 的 SSM 参数（例如，）`ssm:/my/ami/parameter`
+ **Image Builder 版本 ARN** — 图像生成器图像版本 ARN
## 分发重试
如果图像分发失败，请使用 `RetryImage` API 重试分发。这避免了完整的映像重建，从而缩短了排除故障原因的时间。`RetryImage`在解决分发失败的根本原因后使用。
RetryImage API 接受映像构建版本 ARN（例如）。`arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1`当您调用 API 时，Image Builder 会使用原始分发配置和设置自动从故障点恢复分发过程。`RetryImage`API 可以重试在分发阶段、测试阶段或集成阶段失败的分发。它适用于以下状态：待处理、失败、已删除或可用。 AMIs
**先决条件**
在重试分发之前，请确保满足以下条件：
+ 您已经确定并解决了失败的根本原因。查看日志中的分发 CloudWatch 日志，了解错误详情。
+ 您拥有重试镜像构建所必需的 IAM 权限。
+ 对于跨账户分发失败，请验证目标账户`EC2ImageBuilderDistributionCrossAccountRole`中的是否已附加`Ec2ImageBuilderCrossAccountDistributionAccess`策略。
**重要：**如果不修复根本问题，重试将导致重复失败。
## 分发工作流程
分发工作流是一种新的工作流类型，它补充了构建和测试工作流程，使您能够通过顺序步骤定义和控制分发流程。通过分发工作流程，您可以创建自定义分发流程，包括 AMI 复制操作、 wait-for-action检查点、图像属性修改和其他与分发相关的步骤。这提供了对分布方式的结构化控制， AMIs 包括分步级可见性、并行分发功能和精细的错误报告。
要了解有关创建和自定义工作流程的更多信息，请参阅[管理图像工作流程](manage-image-workflows.html)。