View a markdown version of this page

使用 Image Builder 创建一个自定义组件 - EC2 Image Builder
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

使用 Image Builder 创建一个自定义组件

完成组件文档后,您可以使用它来创建 Image Builder 配方可以使用的自定义组件。您可以通过 Image Builder 控制台、通过 API 或 SDK,或者通过命令行创建自定义组件。有关如何创建带输入参数的自定义组件并在配方中使用该组件的更多信息,请参阅教程:创建带有输入参数的自定义组件。

以下各节向您展示如何从控制台创建组件, Amazon CLI,或 Amazon Tools for PowerShell。

在控制台中创建自定义组件

提示

现在你可以使用 AI 进行创作。有关更多信息,请参阅 使用 AI 创建和更新资源-预览。

创建一个 EC2 TOE 使用映像生成器控制台中的应用程序组件,请执行以下步骤:

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

  2. 在导航窗格中选择组件。然后,选择 Create component (创建组件)。

  3. 在 Create component (创建组件) 页面上的 Component details (组件详细信息) 下,输入以下内容:

    1. Image Operating system (OS) (镜像操作系统 (OS))。指定与该组件兼容的操作系统。

    2. Component category (组件类别)。从下拉列表中,选择要创建的生成或测试组件的类型。

    3. Component name (组件名称)。输入组件的名称。

    4. Component version (组件版本)。输入组件的版本号。

    5. 描述。提供可选的描述以帮助您标识组件。

    6. Change description (更改描述)。提供可选的描述,以帮助您了解对该组件版本进行的更改。

  4. 在定义文档部分中,默认选项为定义文档内容。组件文档定义了 Image Builder 在构建和测试实例上执行的用于创建映像的操作。

    在内容框中,输入您的 YAML 组件文档内容。要从 Linux 的 Hello World 示例开始,请选择使用示例选项。要了解有关如何创建 YAML 组件文档或从该页面复制并粘贴 UpdateOS 示例的更多信息,请参阅 在 Image Builder 中为自定义组件创建 YAML 组件文档。

  5. 在输入组件详细信息后,选择创建组件。

    注意

    要在创建或更新配方时查看您的新组件,请将我拥有的筛选条件应用于构建或测试组件列表。筛选条件位于组件列表顶部的搜索框旁边。

  6. 要删除组件,请从 Components (组件) 页面中选中要删除的组件旁边的复选框。从 Actions (操作) 下拉列表中,选择 Delete component (删除组件)。

更新组件

要创建新的组件版本,请遵循以下步骤:

  1. 取决于您从哪个位置开始:

    • 从组件列表页面 — 选中组件名称旁边的复选框,然后从操作菜单中选择创建新版本。

    • 从组件详情页面 — 选择标题右上角的创建新版本按钮。

  2. 当显示创建组件页面时,组件信息已使用当前值进行填充。按照创建组件步骤更新组件。确保在中输入唯一的语义版本 组件版本。要了解有关 Image Builder 资源的语义版本控制的更多信息,请参阅Image Builder 中的语义版本控制。

从中创建自定义组件 Amazon CLI

在本节中,您将学习如何在中设置和使用映像生成器命令 Amazon CLI 创建一个 EC2 TOE 应用程序组件,如下所示:

  • 将您的 YAML 组件文档上传到可以从命令行引用的 S3 存储桶。

  • 创建 EC2 TOE 应用程序组件带有 create-component 命令。

  • 使用 list-components 命令和名称筛选器列出组件版本,以查看已存在哪些版本。您可以使用输出来确定应使用哪个版本进行更新。

创建一个 EC2 TOE 来自输入 YAML 文档的应用程序组件,按照与您的映像操作系统平台相匹配的步骤进行操作。

Linux
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 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 你在中使用的命令 Amazon CLI,创建一个 JSON 文件,其中包含要传递给命令的所有组件参数。包括您在前面创建的 update-linux-os.yaml 文档的位置。uri 键值对包含文件引用。

注意

JSON 文件中数据值的命名约定遵循为映像生成器 API 操作请求参数指定的模式。要查看 API 命令请求参数,请参阅 EC2 Image Builder API 参考中的 CreateComponent 命令。

要将数据值作为命令行参数提供,请参阅《Amazon 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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "security-updates" } }
  2. 创建组件

    使用以下命令创建组件,引用您在上一步中创建的 JSON 文件的文件名:

    aws imagebuilder create-component --cli-input-json file://create-update-linux-os-component.json
    注意
    • JSON 文件路径开头必须包含 file:// 符号。

    • JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如,Windows 使用反斜杠 (\) 引用目录路径,而 Linux 和 macOS 使用正斜杠 (/)。

Windows
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 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 你在中使用的命令 Amazon CLI,创建一个 JSON 文件,其中包含要传递给命令的所有组件参数。包括您在前面创建的 update-windows-os.yaml 文档的位置。uri 键值对包含文件引用。

注意

JSON 文件中数据值的命名约定遵循为映像生成器 API 操作请求参数指定的模式。要查看 API 命令请求参数,请参阅 EC2 Image Builder API 参考中的 CreateComponent 命令。

要将数据值作为命令行参数提供,请参阅《Amazon 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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "security-updates" } }
    注意
    • JSON 文件路径开头必须包含 file:// 符号。

    • JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如,Windows 使用反斜杠 (\) 引用目录路径,而 Linux 和 macOS 使用正斜杠 (/)。

  2. 创建组件

    使用以下命令创建组件,引用您在上一步中创建的 JSON 文件的文件名:

    aws imagebuilder create-component --cli-input-json file://create-update-windows-os-component.json
    注意
    • JSON 文件路径开头必须包含 file:// 符号。

    • JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如,Windows 使用反斜杠 (\) 引用目录路径,而 Linux 和 macOS 使用正斜杠 (/)。

macOS
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 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 你在中使用的命令 Amazon CLI,创建一个 JSON 文件,其中包含要传递给命令的所有组件参数。包括您在前面创建的 wget-macos.yaml 文档的位置。uri 键值对包含文件引用。

注意

JSON 文件中数据值的命名约定遵循为映像生成器 API 操作请求参数指定的模式。要查看 API 命令请求参数,请参阅 EC2 Image Builder API 参考中的 CreateComponent 命令。

要将数据值作为命令行参数提供,请参阅《Amazon CLI 命令引用》中指定的参数名称。

  1. 创建 CLI 输入 JSON 文件

    使用文件编辑工具创建名为 install-wget-macos-component.json 的文件。包括以下内容:

    { "name": "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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "install-software" } }
  2. 创建组件

    使用以下命令创建组件,引用您在上一步中创建的 JSON 文件的文件名:

    aws imagebuilder create-component --cli-input-json file://install-wget-macos-component.json
    注意
    • JSON 文件路径开头必须包含 file:// 符号。

    • JSON 文件的路径应遵循运行命令的基本操作系统的相应约定。例如,Windows 使用反斜杠 (\) 引用目录路径,而 Linux 和 macOS 使用正斜杠 (/)。

EC2 TOE 更新组件版本控制

EC2 TOE 组件名称和版本嵌入在组件的亚马逊资源名称 (ARN) 中,位于组件前缀之后。组件的每个新版本都有自己唯一的 ARN。创建新版本的步骤与创建新组件的步骤完全相同,前提是该组件名称的语义版本是唯一的。要了解有关 Image Builder 资源的语义版本控制的更多信息,请参阅Image Builder 中的语义版本控制。

为确保分配下一个逻辑版本,请首先获取要更改的组件的现有版本列表。

Amazon CLI

使用 list-components 使用 Amazon CLI,然后根据名称进行过滤。

在此示例中,您将根据在前面的 Linux 示例中创建的组件的名称进行筛选。要列出您创建的组件,请使用值 name 来自您在中使用的 JSON 文件中的参数 create-component 命令:

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:111122223333:component/update-linux-os/1.0.0", "name": "update-linux-os", "version": "1.0.0", "platform": "Linux", "type": "BUILD", "owner": "111122223333", "dateCreated": "2020-09-24T16:58:24.444Z" }, { "arn": "arn:aws:imagebuilder:us-west-2:111122223333:component/update-linux-os/1.0.1", "name": "update-linux-os", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "111122223333", "dateCreated": "2021-07-10T03:38:46.091Z" } ] }
PowerShell

使用 Get-EC2IBComponentList 带有 cmdlet Filter 参数,然后根据名称进行过滤。

在此示例中,您将筛选您在中创建的 Linux 组件的名称 从中创建自定义组件 Amazon Tools for PowerShell。要列出您创建的组件,请使用值 Name 您与... 一起使用的参数 New-EC2IBComponent cmdlet:

Get-EC2IBComponentList -Filter @{Name="name";Values="update-linux-os"}

cmdlet 为组件的每个版本返回一个对象。每个对象都包含组件 Arn, Name, Version, Platform, Type, Owner,以及 DateCreated。

根据您的结果,您可以确定下一个版本应该是什么。

从中创建自定义组件 Amazon Tools for PowerShell

在本节中,您将学习如何在中使用图像生成器 cmdlet Amazon Tools for PowerShell 创建一个 EC2 TOE 应用程序组件,如下所示:

这个 New-EC2IBComponent cmdlet 将每个组件设置作为单独的参数,因此您不需要 JSON 输入文件。本节中的每个示例都使用与中的匹配平台示例相同的值 从中创建自定义组件 Amazon CLI。

注意

大多数 cmdlet 参数名称都与映像生成器 API 操作的请求参数相匹配,以 Pascal 为例。例如, semanticVersion 变成 SemanticVersion,以及 kmsKeyId 变成 KmsKeyId。这个 Tag 参数采用标签键和值的哈希表。要查看 API 请求参数,请参阅 CreateComponent 中的操作 EC2 映像生成器 API 参考。

要创建一个 EC2 TOE 来自输入 YAML 文档的应用程序组件,按照与您的映像操作系统平台相匹配的步骤进行操作。

Linux
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 Amazon S3

    如果您的文档小于 64 KB,则可以跳过此步骤。大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。

    要上传文档,请运行 Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/update-linux-os.yaml ` -File update-linux-os.yaml
从 YAML 文档创建组件

使用 Uri 用于引用的参数 update-linux-os.yaml 您之前上传的文档。

  • 创建组件

    要创建组件,请运行 New-EC2IBComponent cmdlet:

    New-EC2IBComponent -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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "security-updates" }
Windows
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 Amazon S3

    如果您的文档小于 64 KB,则可以跳过此步骤。大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。

    要上传文档,请运行 Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/update-windows-os.yaml ` -File update-windows-os.yaml
从 YAML 文档创建组件

使用 Uri 用于引用的参数 update-windows-os.yaml 您之前上传的文档。

  • 创建组件

    要创建组件,请运行 New-EC2IBComponent cmdlet:

    New-EC2IBComponent -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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "security-updates" }
macOS
将您的应用程序组件文档存储到 Amazon S3 中

您可以使用 S3 存储桶作为您的存储库 EC2 TOE 应用程序组件源文档。要存储组件文档,请按照以下步骤操作:

  • 将文档上传到 Amazon S3

    如果您的文档小于 64 KB,则可以跳过此步骤。大小为 64 KB 或更大的文档必须存储在 Amazon S3 中。

    要上传文档,请运行 Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/wget-macos.yaml ` -File wget-macos.yaml
从 YAML 文档创建组件

使用 Uri 用于引用的参数 wget-macos.yaml 您之前上传的文档。

  • 创建组件

    要创建组件,请运行 New-EC2IBComponent cmdlet:

    New-EC2IBComponent -Name 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:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "install-software" }

导入脚本来创建组件

在某些情况下,从预先存在的脚本入手可能更容易一些。对于本文中的情况,您可以使用以下示例。

这个例子使用了 PowerShell 脚本名为 admin-config.ps1 你已经上传到的 amzn-s3-demo-source-bucket。目前,唯一支持的组件格式是 SHELL。

Amazon CLI

此示例假设你有一个名为的文件 import-component.json。该文件包含以下内容:

{ "name": "my-imported-component", "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/admin-config.ps1", "kmsKeyId": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222" }

要从导入的脚本创建组件,请运行以下命令:

aws imagebuilder import-component --cli-input-json file://import-component.json
PowerShell

此示例使用与相同的值 Amazon CLI 示例。用途的工具 PowerShell 不采用 JSON 输入文件。相反,每个 JSON 密钥都是一个 cmdlet 参数。例如, semanticVersion 变成 SemanticVersion,以及 uri 变成 Uri。

要从导入的脚本创建组件,请运行 Import-EC2IBComponent cmdlet:

Import-EC2IBComponent -Name my-imported-component ` -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/admin-config.ps1 ` -KmsKeyId arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222

自动编译版本管理

当您创建名称和语义版本与现有组件相同的组件时,Image Builder 会自动递增编译版本号(例如,从 /1 到 /2,到 /3,依此类推)。这使您无需手动管理版本号即可对组件进行迭代更新,这在以下情况下特别有用 CI/CD 管道和基础设施即代码部署。如果组件内容与之前的构建版本相同,则映像生成器返回 ResourceAlreadyExistsException 以防止重复的组件消耗您的服务配额。

使用版本引用

创建或检索组件时,Image Builder 会自动为预构的 ARN 提供最新版本的通配符版本模式VersionReferences 对象。这些参考可以轻松地在配方和管道中使用最新版本的组件,而无需手动解析 ARN。

选择正确的版本参考

以下列表描述了何时使用每个版本引用:

  • 最新VersionArn (x.x.x)-始终使用绝对最新的组件版本。

  • 最新MajorVersionArn (1.x.x)-使用主要版本中最新的次要版本和补丁版本。

  • 最新MinorVersionArn (1.2.x)-仅使用最新的补丁版本。

  • 最新PatchVersionArn (1.2.3)-引用特定的语义版本,但获取最新的构建版本。