本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
使用 AWSTOE 自定义组件的组件文档框架
要使用 AWS Task Orchestrator and Executor (AWSTOE) 组件框架构建组件，必须提供一个 YAML-based 文档，该文档表示适用于您创建的组件的阶段和步骤。 AWS 服务 当他们创建新的亚马逊系统映像 (AMI) 或容器映像时，请使用您的组件。
主题
组件文档工作流程
AWSTOE 组件文档使用阶段和步骤对相关任务进行分组，并将这些任务组织成组件的逻辑工作流程。
提示
使用您的组件构建映像的服务可能会实施有关构建过程使用哪些阶段，以及何时允许这些阶段运行的规则。您在设计组件时，请务必考虑这一点。
阶段
阶段表示您的工作流程在映像构建过程中的进展。例如，Image Builder 服务在其构建阶段对其生成的映像使用 build 和 validate 阶段。它在测试阶段使用 test 和 container-host-test 阶段来确保在创建最终 AMI 或分发容器映像之前，映像快照或容器映像产生预期的结果。
当组件运行时，每个阶段的关联命令将按照它们在组件文档中出现的顺序进行应用。
阶段规则
-
每个阶段名称在文档中必须是唯一的。
-
您可以在文档中定义多个阶段。
-
您必须在文档中至少包含以下至少一个阶段：
-
构建 — 对于 Image Builder，此阶段通常在构建阶段使用。
-
验证 — 对于 Image Builder，此阶段通常在构建阶段使用。
-
测试 — 对于 Image Builder，此阶段通常在测试阶段使用。
-
-
阶段始终按照文档中定义的顺序运行。中为 AWSTOE 命令指定它们的顺序 AWS CLI 无效。
Steps
步骤是定义每个阶段中的工作流程的各个工作单元。步骤按先后顺序运行。但是，一个步骤的输入或输出也可以作为输入馈送到后续步骤中。这就是所谓的“链”。
步骤规则
-
步骤名称对于阶段来说必须是唯一的。
-
步骤必须使用可返回退出代码的支持的操作（操作模块）。
有关支持的操作模块、其工作原理、 input/output 值和示例的完整列表，请参阅支持的操作模块 AWSTOE 组件管理器。
组件日志
AWSTOE 每次运行组件时，都会在 EC2 实例上创建一个新的日志文件夹，用于构建和测试新映像。对于容器映像，日志文件夹存储在容器中。
为了帮助在图像创建过程中出现问题时进行故障排除，运行组件时 AWSTOE 创建的输入文档和所有输出文件都存储在日志文件夹中。
日志文件夹名称由以下部分组成：
-
日志目录 — 当服务运行 AWSTOE 组件时，它会与该命令的其他设置一起传入日志目录。在以下示例中，我们展示了 Image Builder 使用的日志文件格式。
-
Linux 和 macOS：
/var/lib/amazon/toe/ -
Windows：
$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\
-
-
文件前缀 — 这是用于所有组件的标准前缀：“
TOE_”。 -
运行时间-这是 YYYY-MM-DD HH-MM-SS _ UTC-0 格式的时间戳。
-
执行 ID-这是 AWSTOE 运行一个或多个组件时分配的 GUID。
示例：/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4
AWSTOE 在日志文件夹中存储以下核心文件：
输入文件
-
document.yaml — 用作命令输入的文档。组件运行后，该文件将作为构件存储。
输出文件
-
application.log — 应用程序日志包含来自 AWSTOE 、带有时间戳的调试级别信息，这些信息有关组件运行时发生的情况。
-
detailedoutput.json — 此 JSON 文件包含有关组件运行时适用于组件的所有文档、阶段和步骤的运行状态、输入、输出和失败的详细信息。
-
console.log — 控制台日志包含组件运行时 AWSTOE 写入控制台的所有标准输出 (stdout) 和标准错误 (stderr) 信息。
-
chaining.json — 此 JSON 文件表示 AWSTOE 应用于解析链接表达式的优化。
注意
日志文件夹还可能包含此处未涵盖的其他临时文件。
输入和输出链
AWSTOE 配置管理应用程序提供了一种通过编写以下格式的参考文献来链接输入和输出的功能：
{{ phase_name.step_name.inputs/outputs.variable
}}
或者
{{ phase_name.step_name.inputs/outputs[index].variable
}}
通过使用链功能，您可以回收代码并提高文档的可维护性。
链式规则
-
只能在每个步骤的输入部分中使用链表达式。
-
具有链表达式的语句必须用引号引起来。例如：
-
无效的表达式：
echo {{ phase.step.inputs.variable }} -
有效的表达式：
"echo {{ phase.step.inputs.variable }}" -
有效的表达式：
'echo {{ phase.step.inputs.variable }}'
-
-
链表达式可以引用同一文档中的其他步骤和阶段的变量。但是，调用服务可能有一些规则，要求链表达式只能在单个阶段的上下文中运行。例如，Image Builder 不支持从构建阶段到测试阶段的链接，因为它独立运行每个阶段。
-
链表达式中的索引从零开始。索引以零 (0) 开头，以引用第一个元素。
示例
要在以下示例步骤的第二个条目中引用源变量，链模式为 {{
build.。SampleS3Download.inputs[1].source
}}
phases: - name: 'build' steps: - name:SampleS3Downloadaction: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\sample2.ps1'
要引用以下示例步骤的输出变量（等于“Hello”），链模式为 {{
build.。SamplePowerShellStep.outputs.stdout
}}
phases: - name: 'build' steps: - name:SamplePowerShellStepaction: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"'
文档架构和定义
以下是文档的 YAML 架构。
name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs:
文档的架构定义如下所示。
| 字段 | 描述 | Type | 必填 |
|---|---|---|---|
| name | 文档的名称。 | 字符串 | 否 |
| 描述 | 文档的描述。 | 字符串 |
否 |
| schemaVersion | 文档的架构版本，当前为 1.0。 | 字符串 |
是 |
| phases | 阶段及其步骤的列表。 |
列表 |
是 |
该schemaVersion字段接受"1.0"或"1"（标准化为"1.0"）。 AWSTOE 不支持其他架构版本。
可以在文档、阶段或步骤true级别将可选disableLogging字段设置为。此设置禁止该作用域的日志输出。将此设置用于处理敏感数据的步骤。
阶段的架构定义如下所示。
| 字段 | 描述 | Type | 必填 |
|---|---|---|---|
| name |
阶段的名称。相名必须符合以下规则：
|
字符串 | 是 |
| 步骤 | 阶段中的步骤列表。 | 列表 |
是 |
步骤的架构定义如下所示。
| 字段 | 描述 | Type | 必填 | 默认 值 |
|---|---|---|---|---|
| name |
User-defined 步骤的名称。步骤名称必须符合以下规则：
|
字符串 | ||
| action | 与运行步骤的模块相关的关键字。 | 字符串 | ||
| timeoutSeconds |
在失败或重试之前，步骤运行的秒数。 此外，支持 -1 值，表示无限超时。不允许 0 和其他负值。 |
整数 |
否 |
7,200 秒（120 分钟） |
| onFailure |
指定该步骤在失败时应执行的操作。有效值如下所示：
|
字符串 |
否 |
中止 |
| maxAttempts | 在步骤失败之前允许的最大尝试次数。 | 整数 |
否 |
1 |
| inputs | 包含操作模块运行步骤所需的参数。 | 字典 |
是 |
文档示例
以下示例显示了为目标操作系统执行任务的 AWSTOE 组件文档。
