本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Image Builder 如何使用 EC2 Task Orchestrator and Executor 用于管理组件的应用程序 EC2 Image Builder 使用 EC2 Task Orchestrator and Executor (EC2 TOE) 应用程序来编排复杂的工作流程、修改系统配置和测试映像，而无需额外的 devops 脚本或代码。此应用程序管理和运行使用其声明性文档架构的组件。 EC2 TOE 是一个独立的应用程序，当您创建映像时，Image Builder 会将其安装在其构建和测试实例上。您也可以在 EC2 实例上手动安装，以创建自己的自定义组件。它不需要任何其他设置，也可以在本地运行。 **Topics** + [EC2 TOE 下载](#toe-downloads) + [支持的区域：](#toe-supported-regions) + [EC2 TOE 命令参考](#toe-commands) + [手动设置以开发自定义组件 EC2 TOE](toe-get-started.md) + [使用 EC2 TOE 自定义组件的组件文档框架](toe-use-documents.md) + [支持的操作模块 EC2 TOE 组件管理器](toe-action-modules.md) + [配置输入 EC2 TOE 运行命令](toe-run-config-input.md) ## EC2 TOE 下载 要进行安装 EC2 TOE，请选择适用于您的架构和平台的下载链接。如果您连接到服务的 VPC 终端节点（例如 Image Builder），则该终端节点必须附加自定义终端节点策略，其中包括访问 S3 存储桶进行 EC2 TOE 下载的权限。否则，您的构建和测试实例将无法下载引导脚本 (`bootstrap.sh`) 并安装 EC2 TOE 应用程序。有关更多信息，请参阅 [为 Image Builder 创建 VPC 端点策略](vpc-interface-endpoints.md#vpc-endpoint-policy)。 **重要** Amazon 正在逐步取消对 TLS 版本 1.0 和 1.1 的支持。要访问 S3 存储桶进行 EC2 TOE 下载，您的客户端软件必须使用 TLS 版本 1.2 或更高版本。有关更多信息，请参阅[Amazon 此博客文章](https://www.amazonaws.cn/blogs/security/tls-1-2-required-for-aws-endpoints/)。 | 架构 | 平台 | 下载链接 | 示例 | | --- | --- | --- | --- | | 386 | AL 2 和 2023
RHEL 7、8 和 9
Ubuntu 16.04、18.04、20.04、22.04 和 24.04
CentOS 7 和 8
SUSE 12 和 15 | `https://awstoe-.s3..amazonaws.com/latest/linux/386/awstoe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe) | | AMD64 | AL 2 和 2023
RHEL 7、8 和 9
Ubuntu 16.04、18.04、20.04、22.04 和 24.04
CentOS 7 和 8
CentOS Stream 8
SUSE 12 和 15 | https://awstoe-.s3..amazonaws.com/latest/linux/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe) | | AMD64 | macOS 10.14.x (Mojave)、10.15.x (Catalina)、11.x (Big Sur)、12.x (Monterey) | https://awstoe-{{region}}.s3.{{region}}.amazonaws.com/latest/darwin/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe) | | AMD64 | Windows Server 2012 R2、2016、2019 和 2022 | `https://awstoe-.s3..amazonaws.com/latest/windows/amd64/awstoe.exe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe) | | ARM64 | AL 2 和 2023
RHEL 7、8 和 9
Ubuntu 16.04、18.04、20.04、22.04 和 24.04
CentOS 7 和 8
CentOS Stream 8
SUSE 12 和 15 | https://awstoe-.s3..amazonaws.com/latest/linux/arm64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe) | ## 支持的区域： EC2 TOE 在以下区域支持作为独立应用程序。 | Amazon Web Services 区域 名字 | Amazon Web Services 区域 | | --- | --- | | 美国东部（俄亥俄州） | us-east-2 | | 美国东部（弗吉尼亚州北部） | us-east-1 | | Amazon GovCloud (US-East) | us-gov-east-1 | | Amazon GovCloud (US-West) | us-gov-west-1 | | 美国西部（北加利福尼亚） | us-west-1 | | 美国西部（俄勒冈州） | us-west-2 | | 非洲（开普敦） | af-south-1 | | 亚太地区（香港） | ap-east-1 | | 亚太地区（大阪） | ap-northeast-3 | | 亚太地区（首尔） | ap-northeast-2 | | 亚太地区 (孟买) | ap-south-1 | | 亚太地区（海得拉巴） | ap-south-2 | | 亚太地区（新加坡） | ap-southeast-1 | | 亚太地区（悉尼） | ap-southeast-2 | | 亚太地区（雅加达） | ap-southeast-3 | | 亚太地区（东京） | ap-northeast-1 | | 加拿大（中部） | ca-central-1 | | 欧洲地区（法兰克福） | eu-central-1 | | 欧洲（苏黎世） | eu-central-2 | | 欧洲地区（斯德哥尔摩） | eu-north-1 | | 欧洲地区（米兰） | eu-south-1 | | 欧洲（西班牙） | eu-south-2 | | 欧洲地区（爱尔兰） | eu-west-1 | | 欧洲地区（伦敦） | eu-west-2 | | 欧洲地区（巴黎） | eu-west-3 | | 以色列（特拉维夫） | il-central-1 | | 中东（阿联酋）： | me-central-1 | | 中东（巴林） | me-south-1 | | 南美洲（圣保罗） | sa-east-1 | | 中国（北京） | cn-north-1 | | 中国（宁夏） | cn-northwest-1 | ## EC2 TOE 命令参考 EC2 TOE 是一款在 Amazon EC2 实例上运行的命令行组件管理应用程序。当 Image Builder 启动 EC2 构建或测试实例时，它会安装在该实例 EC2 TOE 上。然后，它会在中运行 EC2 TOE 命令 Amazon CLI 来安装或验证镜像或容器配方中指定的组件。 **注意** 某些 EC2 TOE 操作模块需要更高的权限才能在 Linux 服务器上运行。要使用提升的权限，请在命令语法前加上前缀 **sudo**，或者在登录时运行 **sudo su** 命令，然后再运行下面链接的命令。有关 EC2 TOE 操作模块的更多信息，请参见[支持的操作模块 EC2 TOE 组件管理器](toe-action-modules.md)。 ***[运行](#cmd-run)*** 使用 **run** 命令为一个或多个组件文档运行 YAML 文档脚本。 ***[验证](#cmd-validate)*** 使用 **validate** 命令为一个或多个组件文档验证 YAML 文档语法。 ### awstoe run command 该命令按 `--config` 参数指定的配置文件或 `--documents` 参数指定的组件文档列表中 YAML 组件文档脚本的内置顺序运行 YAML 组件文档脚本。 **注意** 您必须准确指定下列参数之一，切勿同时指定两个参数： --config --documents #### 语法 ``` awstoe run [--config ] [--cw-ignore-failures ] [--cw-log-group ] [--cw-log-region {{us-west-2}}] [--cw-log-stream ] [--document-s3-bucket-owner ] [--documents ] [--execution-id ] [--log-directory ] [--log-s3-bucket-name ] [--log-s3-bucket-owner ] [--log-s3-key-prefix ] [--parameters {{name1}}={{value1}},{{name2}}={{value2}}...] [--phases ] [--blocked-action-modules ] [--state-directory ] [--version ] [--help] [--trace] ``` #### 参数和选项 参数 **config{{`./config-example.json`}}** 简写形式：-c {{`./config-example.json`}} 配置文件*（条件性）*。此参数包含 JSON 文件的文件位置，该文件包含此命令正在运行的组件的配置设置。如果在配置文件中指定 **run** 命令设置，则不得指定 `--documents` 参数。有关输入配置的更多信息，请参阅 [配置输入 EC2 TOE 运行命令](toe-run-config-input.md)。 有效位置包括： + 本地文件路径 ({{`./config-example.json`}}) + 一个 S3; URI。(`s3://{{bucket/key}}`) **-cw-ignore-failures** 简写形式： N/A 忽略日志中的 CloudWatch 日志失败。 **--cw-log-group** 简写形式： N/A CloudWatch 日志的`LogGroup`名称。 **--cw-log-region** 简写形式： N/A 适用于 CloudWatch 日志的 Amazon 区域。 **--cw-log-stream** 简写形式： N/A CloudWatch 日志的`LogStream`名称，用于指示将`console.log`文件流式传输到 EC2 TOE 何处。 **--document-s3-bucket-owner** 简写形式： N/A S3 URI-based 文档的存储桶所有者的账户 ID。 **--文档 {{`./doc-1.yaml`,`./doc-n.yaml`}}** 简写形式：-d {{`./doc-1.yaml`}},{{`./doc-n`}} 组件文档*（条件性）*。此参数包含以逗号分隔的文件位置列表，以供运行 YAML 组件文档。如果您使用 `--documents` 参数为 **run** 命令指定 YAML 文档，则不得指定 `--config` 参数。不要在列表中的项目之间包含空格。 有效位置包括： + 本地文件路径 ({{./component-doc-example.yaml}})。 + S3 URI (`s3://{{bucket/key}}`)。 + Image Builder 组件构建版本 ARN (arn: aws: imagebuilder: us-west--: component/ /2021.12。{{2:123456789012}} {{my-example-component}} 02/1)。 **--execution-id** 简写形式：-i 这是适用于执行当前 **run** 命令的唯一 ID。此 ID 包含在输出和日志文件名中，用于唯一标识这些文件，并将它们链接到当前的命令执行。如果省略此设置，则 EC2 TOE 生成 GUID。 **--log-directory** 简写形式：-l EC2 TOE 存储此命令执行的所有日志文件的目标目录。默认情况下，该目录位于以下父目录中：`TOE__`。如果未指定日志目录，则 EC2 TOE 使用当前工作目录 (`.`)。 **--log-s3-bucket-name** 简写形式：-b 如果组件日志存储在 Amazon S3 中（推荐），则将组件应用程序日志 EC2 TOE 上传到此参数中命名的 S3 存储桶。 **--log-s3-bucket-owner** 简写形式： N/A 如果组件日志存储在 Amazon S3 中（推荐），则这是 EC2 TOE 写入日志文件的存储桶的所有者账户 ID。 **--log-s3-key-prefix** 简写形式：-k 如果组件日志存储在 Amazon S3 中（推荐），则这是存储桶中日志位置的 S3 对象键前缀。 **--参数 {{name1}} ={{value1}}，{{name2}}={{value2}}...** 简写形式： N/A 参数是在组建文档中定义的可变变量，其设置由调用应用程序在运行时提供。 **--phases** 简写形式：-p 以逗号分隔的列表，它指定要从 YAML 组件文档中运行哪些阶段。如果组件文档包含其他阶段，则这些阶段将无法运行。 **--state-directory** 简写形式：-s 存储状态跟踪文件的文件路径。 **--屏蔽动作模块** 简写形式： N/A 以逗号分隔的操作模块列表，这些模块无法在组件文档中运行。如果文档包含被屏蔽的操作模块，则验证将在开始执行之前失败。 **--version** 简写形式：-v 指定组件应用程序版本。选项 **--help** 简写形式：-h 显示使用组件管理应用程序选项的帮助手册。 **--trace** 简写形式：-t 启用对控制台的详细日志记录。 #### Output 该**run**命令生成 JSON 执行摘要。以下示例显示了成功执行的输出。 ``` { "executionId": "12345678-abcd-efgh-1234-example12345", "status": "success", "failedStepCount": 0, "executedStepCount": 3, "ignoredFailedStepCount": 0, "skippedStepCount": 0, "failureMessage": "", "logUrl": "s3://my-bucket/my-prefix/12345678-abcd-efgh-1234-example12345" } ``` 该`status`字段报告总体执行结果： + `success`— 所有阶段和步骤均成功完成。 + `failed`— 一个或多个步骤失败，因为`onFailure`操作是`Abort`。 + `timedOut`— 一个或多个步骤超过了其`timeoutSeconds`值。 ### awstoe validate command 运行此命令时，它会验证 `--documents` 参数指定的每个组件文档的 YAML 文档语法。 #### 语法 ``` awstoe validate [--blocked-action-modules ] [--document-s3-bucket-owner ] --documents [--help] [--trace] ``` #### 参数和选项 参数 **--屏蔽动作模块** 简写形式： N/A 以逗号分隔的操作模块列表，这些模块无法在组件文档中运行。如果文档包含被屏蔽的操作模块，则验证失败。 **--document-s3-bucket-owner** 简写形式： N/A 提供的 S3 URI-based 文档的源账户 ID。 **--文档 {{`./doc-1.yaml`,`./doc-n.yaml`}}** 简写形式：-d {{`./doc-1.yaml`}},{{`./doc-n`}} 组件文档*（必填）*。此参数包含以逗号分隔的 YAML 组件文档要运行的文件位置列表，项目之间没有空格。有效位置包括： + 本地文件路径 ({{./component-doc-example.yaml}}) + S3 URI (`s3://{{bucket/key}}`) + Image Builder 组件构建版本 ARN (arn: aws: imagebuilder: us-west--: component/ /2021.12。{{2:123456789012}} {{my-example-component}} 02/1)选项 **--help** 简写形式：-h 显示使用组件管理应用程序选项的帮助手册。 **--trace** 简写形式：-t 启用对控制台的详细日志记录。 #### Output 该**validate**命令生成 JSON 验证结果。以下示例显示了成功验证的输出。 ``` { "validationStatus": "success", "message": "Validation successful." } ``` 以下示例显示了验证失败时的输出。 ``` { "validationStatus": "failed", "message": "Document has 0 phases. Phases list must not be empty." } ```