本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Image Builder 创建一个自定义组件
完成组件文档后，您可以使用它来创建 Image Builder 配方可以使用的自定义组件。您可以通过 Image Builder 控制台、API 或 SDKs命令行创建自定义组件。有关如何创建带输入参数的自定义组件并在配方中使用该组件的更多信息，请参阅[教程：创建带有输入参数的自定义组件](tutorial-component-parameters.md)。
以下各节将向您介绍如何通过控制台或通过 AWS CLI创建组件。
**Topics**
+ [通过控制台创建自定义组件](#create-component-ib-console)
+ [从中创建自定义组件 AWS CLI](#create-component-ib-cli)
+ [导入脚本以从中创建组件 AWS CLI](#import-component-cli)
+ [自动生成版本管理](#auto-build-version-management)
+ [使用版本引用](#using-version-references)
## 通过控制台创建自定义组件
要通过 Image Builder 控制台创建 AWSTOE 应用程序组件，请执行以下步骤：
1. 打开 EC2 Image Builder 控制台，网址为[https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。
1. 在导航窗格中选择**组件**。然后，选择 **Create component (创建组件)**。
1. 在 **Create component (创建组件)** 页面上的 **Component details (组件详细信息)** 下，输入以下内容：
1. **Image Operating system (OS) (镜像操作系统 (OS))**。指定与该组件兼容的操作系统。
1. **Component category (组件类别)**。从下拉列表中，选择要创建的生成或测试组件的类型。
1. **Component name (组件名称)**。输入组件的名称。
1. **Component version (组件版本)**。输入组件的版本号。
1. **描述**。提供可选的描述以帮助您标识组件。
1. **Change description (更改描述)**。提供可选的描述，以帮助您了解对该组件版本进行的更改。
1. 在**定义文档**部分中，默认选项为**定义文档内容**。组件文档定义了 Image Builder 在构建和测试实例上执行的用于创建映像的操作。
在**内容**框中，输入您的 YAML 组件文档内容。要从 Linux 的 *Hello World* 示例开始，请选择**使用示例**选项。要了解有关如何创建 YAML 组件文档或从该页面复制并粘贴 *UpdateOS* 示例的更多信息，请参阅 [在 Image Builder 中为自定义组件创建 YAML 组件文档](create-component-yaml.md)。
1. 在输入组件详细信息后，选择**创建组件**。
**注意**
要在创建或更新配方时查看您的新组件，请将**我拥有的**筛选条件应用于构建或测试组件列表。筛选条件位于组件列表顶部的搜索框旁边。
1. 要删除组件，请从 **Components (组件)** 页面中选中要删除的组件旁边的复选框。从 **Actions (操作)** 下拉列表中，选择 **Delete component (删除组件)**。
**更新组件**
要创建新的组件版本，请遵循以下步骤：
1. 取决于您从哪个位置开始：
+ 从**组件**列表页面 — 选中组件名称旁边的复选框，然后从**操作**菜单中选择**创建新版本**。
+ 从组件详情页面 — 选择标题右上角的**创建新版本**按钮。
1. 当显示**创建组件**页面时，组件信息已使用当前值进行填充。按照创建组件步骤更新组件。这样可以确保在**组件版本**中输入唯一的语义版本。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
## 从中创建自定义组件 AWS CLI
在本节中，您将学习如何设置和使用中的 Image Builder 命令 AWS CLI 来创建 AWSTOE 应用程序组件，如下所示。
+ 将您的 YAML 组件文档上传到可以从命令行引用的 S3 存储桶。
+ 使用**create-component**命令创建 AWSTOE 应用程序组件。
+ 使用 **list-components** 命令和名称筛选器列出组件版本，以查看已存在哪些版本。您可以使用输出来确定应使用哪个版本进行更新。
要根据输入 YAML 文档创建 AWSTOE 应用程序组件，请按照与您的映像操作系统平台相匹配的步骤进行操作。
------
#### [ Linux ]
**将您的应用程序组件文档存储到 Amazon S3 中**
您可以使用 S3 存储桶作为 AWSTOE 应用程序组件源文档的存储库。要存储组件文档，请按照以下步骤操作：
+
**将文档上传到 Amazon S3**
*如果您的文档小于 64 KB，则可以跳过此步骤。*大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。
```
aws s3 cp update-linux-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml
```
**从 YAML 文档创建组件**
要简化您在中使用的**create-component**命令 AWS CLI，请创建一个 JSON 文件，其中包含要传递给命令的所有组件参数。包括您在前面创建的 `update-linux-os.yaml` 文档的位置。`uri` 键值对包含文件引用。
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 命令请求参数，请参阅 *EC2 Image Builder API 参考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。
要将数据值作为命令行参数提供，请参阅《*AWS CLI 命令引用*》中指定的参数名称。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建名为 `create-update-linux-os-component.json` 的文件。包括以下内容：
```
{
"name": "update-linux-os",
"semanticVersion": "1.1.2",
"description": "An example component that updates the Linux operating system",
"changeDescription": "Initial version.",
"platform": "Linux",
"uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml",
"kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c",
"tags": {
"MyTagKey-purpose": "security-updates"
}
}
```
1.
**创建组件**
使用以下命令创建组件，引用您在上一步中创建的 JSON 文件的文件名：
```
aws imagebuilder create-component --cli-input-json file://create-update-linux-os-component.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
------
#### [ Windows ]
**将您的应用程序组件文档存储到 Amazon S3 中**
您可以使用 S3 存储桶作为 AWSTOE 应用程序组件源文档的存储库。要存储组件文档，请按照以下步骤操作：
+
**将文档上传到 Amazon S3**
*如果您的文档小于 64 KB，则可以跳过此步骤。*大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。
```
aws s3 cp update-windows-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml
```
**从 YAML 文档创建组件**
要简化您在中使用的**create-component**命令 AWS CLI，请创建一个 JSON 文件，其中包含要传递给命令的所有组件参数。包括您在前面创建的 `update-windows-os.yaml` 文档的位置。`uri` 键值对包含文件引用。
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 命令请求参数，请参阅 *EC2 Image Builder API 参考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。
要将数据值作为命令行参数提供，请参阅《*AWS CLI 命令引用*》中指定的参数名称。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建名为 `create-update-windows-os-component.json` 的文件。包括以下内容：
```
{
"name": "update-windows-os",
"semanticVersion": "1.1.2",
"description": "An example component that updates the Windows operating system.",
"changeDescription": "Initial version.",
"platform": "Windows",
"uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml",
"kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c",
"tags": {
"MyTagKey-purpose": "security-updates"
}
}
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
1.
**创建组件**
使用以下命令创建组件，引用您在上一步中创建的 JSON 文件的文件名：
```
aws imagebuilder create-component --cli-input-json file://create-update-windows-os-component.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
------
#### [ macOS ]
**将您的应用程序组件文档存储到 Amazon S3 中**
您可以使用 S3 存储桶作为 AWSTOE 应用程序组件源文档的存储库。要存储组件文档，请按照以下步骤操作：
+
**将文档上传到 Amazon S3**
*如果您的文档小于 64 KB，则可以跳过此步骤。*大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。
```
aws s3 cp wget-macos.yaml s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml
```
**从 YAML 文档创建组件**
要简化您在中使用的**create-component**命令 AWS CLI，请创建一个 JSON 文件，其中包含要传递给命令的所有组件参数。包括您在前面创建的 `wget-macos.yaml` 文档的位置。`uri` 键值对包含文件引用。
**注意**
JSON 文件中数据值的命名约定遵循为 Image Builder API 操作请求参数指定的模式。要查看 API 命令请求参数，请参阅 *EC2 Image Builder API 参考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。
要将数据值作为命令行参数提供，请参阅《*AWS CLI 命令引用*》中指定的参数名称。
1.
**创建 CLI 输入 JSON 文件**
使用文件编辑工具创建名为 `install-wget-macos-component.json` 的文件。包括以下内容：
```
{
"name": "install install-wget-macos-component",
"semanticVersion": "1.1.2",
"description": "An example component that installs and verifies the wget utility on macOS.",
"changeDescription": "Initial version.",
"platform": "macOS",
"uri": "s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml",
"kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c",
"tags": {
"MyTagKey-purpose": "install-software"
}
}
```
1.
**创建组件**
使用以下命令创建组件，引用您在上一步中创建的 JSON 文件的文件名：
```
aws imagebuilder create-component --cli-input-json file://install-wget-macos-component.json
```
**注意**
JSON 文件路径开头必须包含 `file://` 符号。
JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如，Windows 使用反斜杠 (\$1) 引用目录路径，而 Linux 和 macOS 使用正斜杠 (/)。
------
### AWSTOE 组件版本控制，用于来自的更新 AWS CLI
AWSTOE 组件名称和版本嵌入在组件的 Amazon 资源名称 (ARN) 中，位于组件前缀之后。组件的每个新版本都有自己唯一的 ARN。创建新版本的步骤与创建新组件的步骤完全相同，前提是该组件名称的语义版本是唯一的。要了解有关 Image Builder 资源的语义版本控制的更多信息，请参阅[Image Builder 中的语义版本控制](ibhow-semantic-versioning.md)。
为确保分配下一个逻辑版本，请先获取要更改的组件的现有版本列表。使用带有 AWS CLI、并筛选名称的**list-components**命令。
在此示例中，您将根据在前面的 Linux 示例中创建的组件的名称进行筛选。要列出您创建的组件，请使用您在 **create-component** 命令中使用的 JSON 文件中的 `name` 参数值。
```
aws imagebuilder list-components --filters name="name",values="update-linux-os"
{
"requestId": "123a4567-b890-123c-45d6-ef789ab0cd1e",
"componentVersionList": [
{
"arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.0",
"name": "update-linux-os",
"version": "1.0.0",
"platform": "Linux",
"type": "BUILD",
"owner": "123456789012",
"dateCreated": "2020-09-24T16:58:24.444Z"
},
{
"arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.1",
"name": "update-linux-os",
"version": "1.0.1",
"platform": "Linux",
"type": "BUILD",
"owner": "123456789012",
"dateCreated": "2021-07-10T03:38:46.091Z"
}
]
}
```
根据您的结果，您可以确定下一个版本应该是什么。
## 导入脚本以从中创建组件 AWS CLI
在某些情况下，从预先存在的脚本入手可能更容易一些。对于本文中的情况，您可以使用以下示例。
该示例假定您具有一个名为 `import-component.json` 的文件（如下所示）。请注意，该文件直接引用了一个名为的 PowerShell 脚本`AdminConfig.ps1`，该脚本已上传到`amzn-s3-demo-source-bucket`。目前，组件 `format` 支持 `SHELL`。
```
{
"name": "MyImportedComponent",
"semanticVersion": "1.0.0",
"description": "An example of how to import a component",
"changeDescription": "First commit message.",
"format": "SHELL",
"platform": "Windows",
"type": "BUILD",
"uri": "s3://amzn-s3-demo-source-bucket/AdminConfig.ps1",
"kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/60763706-b131-418b-8f85-3420912f020c"
}
```
要从导入后的脚本创建组件，请运行以下命令。
```
aws imagebuilder import-component --cli-input-json file://import-component.json
```
## 自动生成版本管理
当您创建与现有组件具有相同名称和语义版本的组件时，Image Builder 会自动增加构建版本（例如，从`/1`到`/2``/3`、到，等等）。这使您无需手动管理版本号即可对组件进行迭代更新，这在 CI/CD 管道和 infrastructure-as-code部署中特别有用。如果组件内容与之前的构建版本相同，Image Builder 会返回`ResourceAlreadyExistsException`以防止重复的组件消耗您的服务配额。
## 使用版本引用
当您创建或检索组件时，Image Builder 会自动在对象中提供 ARNs 带有通配符的预构版本模式。 latestVersionReferences 这些参考使您可以轻松地在配方和管道中使用最新版本的组件，而无需手动解析 ARNs。
**选择正确的版本参考**
+ latestVersionArn (x.x.x)-始终使用绝对最新的组件版本。
+ atestMajorVersionArn (1.x.x)-在主要版本中使用最新的次要版本和补丁版本。
+ latestMinorVersionArn (1.2.x)-仅使用最新的补丁版本。
+ latestPatchVersionArn (1.2.3)-引用特定的语义版本，但要获取最新的构建版本。