本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为 Image Builder 映像开发自定义组件 您可以创建自己的组件，根据自己的确切规格自定义 Image Builder 映像。使用以下步骤为您的 Image Builder 映像或容器配方开发自定义组件。 1. 如果要开发组件文档并在本地对其进行验证，则可以安装 AWS Task Orchestrator and Executor (AWSTOE) 应用程序并在本地计算机上进行设置。有关更多信息，请参阅 [手动设置以开发自定义组件 AWSTOE](toe-get-started.md)。 1. 创建使用组件文档框架的 AWSTOE 组件文档。有关文档框架的更多信息，请参阅[使用 AWSTOE 组件文档框架创建自定义组件](toe-use-documents.md)。 1. 创建自定义组件时，请指定您的组件文档。有关更多信息，请参阅 [使用 Image Builder 创建一个自定义组件](create-component.md)。 **Topics** + [在 Image Builder 中为自定义组件创建 YAML 组件文档](create-component-yaml.md) + [使用 Image Builder 创建一个自定义组件](create-component.md) # 在 Image Builder 中为自定义组件创建 YAML 组件文档 要构建组件，必须提供 YAML 或者 JSON 应用程序组件文档。该文档包含了在您为提供映像自定义而定义的阶段和步骤中运行的代码。 本节中的一些示例创建了一个构建组件，该组件在 AWSTOE 组件管理应用程序中调用`UpdateOS`操作模块。该模块更新操作系统。有关 `UpdateOS` 操作模块的更多信息，请参阅 [UpdateOS](toe-action-modules.md#action-modules-updateos)。 macOS 操作系统示例使用 `ExecuteBash` 操作模块来安装和验证 `wget` 实用程序。`UpdateOS` 操作模块不支持 macOS。有关 `ExecuteBash` 操作模块的更多信息，请参阅 [ExecuteBash](toe-action-modules.md#action-modules-executebash)。有关 AWSTOE 应用程序组件文档的阶段、步骤和语法的更多信息，请参阅[在 AWSTOE中使用文档](https://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-use-documents.html)。 **注意** Image Builder 根据组件文档中定义的阶段确定组件类型，如下所示： **构建** - 这是默认的组件类型。任何未归类为测试组件的组件都是构建组件。这种类型的组件在映像*构建阶段*运行。如果此构建组件已定义 `test` 阶段，则该阶段在*测试阶段*运行。 **测试** - 要获得测试组件资格，组件文档必须仅包含一个名为 `test` 的阶段。对于与构建组件配置相关的测试，我们建议您不要使用独立的测试组件。相反，在关联的构建组件中使用 `test` 阶段。 有关 Image Builder 如何在其构建过程中使用阶段 (stage) 和时段 (phase) 来管理组件工作流的更多信息，请参阅 [使用组件自定义 Image Builder 映像](manage-components.md)。 要为示例应用程序创建 YAML 应用程序组件文档，请按照与您的映像操作系统匹配的选项卡上的步骤进行操作。 ------ #### [ Linux ] **创建 YAML 组件文件** 使用文件编辑工具创建您的组件文档。文档示例使用名为 `update-linux-os.yaml` 的文件，包含如下内容： ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-linux-os description: Updates Linux with the latest security updates. schemaVersion: 1 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **提示** 在代码环境中使用像在线 [YAML Validat](https://jsonformatter.org/yaml-validator) 或 YAML lint 扩展这样的工具来验证 YAML 格式是否正确。 ------ #### [ Windows ] **创建 YAML 组件文件** 使用文件编辑工具创建您的组件文档。文档示例使用名为 `update-windows-os.yaml` 的文件，包含如下内容： ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-windows-os description: Updates Windows with the latest security updates. schemaVersion: 1.0 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **提示** 在代码环境中使用像在线 [YAML Validat](https://jsonformatter.org/yaml-validator) 或 YAML lint 扩展这样的工具来验证 YAML 格式是否正确。 ------ #### [ macOS ] **创建 YAML 组件文件** 使用文件编辑工具创建您的组件文档。文档示例使用名为 `wget-macos.yaml` 的文件，包含如下内容： ``` name: WgetInstallDocument description: This is wget installation document. schemaVersion: 1.0 phases: - name: build steps: - name: WgetBuildStep action: ExecuteBash inputs: commands: - | PATH=/usr/local/bin:$PATH sudo -u ec2-user brew install wget - name: validate steps: - name: WgetValidateStep action: ExecuteBash inputs: commands: - | function error_exit { echo $1 echo "{\"failureMessage\":\"$2\"}" exit 1 } type wget if [ $? -ne 0 ]; then error_exit "$stderr" "Wget installation failed!" fi - name: test steps: - name: WgetTestStep action: ExecuteBash inputs: commands: - wget -h ``` **提示** 在代码环境中使用像在线 [YAML Validat](https://jsonformatter.org/yaml-validator) 或 YAML lint 扩展这样的工具来验证 YAML 格式是否正确。 ------ # 使用 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)-引用特定的语义版本，但要获取最新的构建版本。 **注意** 为避免意外费用，请务必清理根据本指南中的示例创建的资源和管道。有关删除 Image Builder 中的资源的更多信息，请参阅 [删除过期或未使用的 Image Builder 资源](delete-resources.md)。