本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
使用 AWSTOE 组件文档框架创建自定义组件
要使用 AWS Task Orchestrator and Executor (AWSTOE) 组件框架构建组件,必须提供一个YAML基于文档,该文档表示适用于您创建的组件的阶段和步骤。 AWS 服务 当他们创建新的 Amazon 系统映像 (AMI) 或容器映像时,请使用您的组件。
组件文档工作流程
AWSTOE 组件文档使用阶段和步骤对相关任务进行分组,并将这些任务组织成组件的逻辑工作流程。
提示
使用您的组件构建映像的服务可能会实施有关构建过程使用哪些阶段,以及何时允许这些阶段运行的规则。您在设计组件时,请务必考虑这一点。
阶段
阶段表示您的工作流程在映像构建过程中的进展。例如,Image Builder 服务在其构建阶段对其生成的映像使用 build
和 validate
阶段。它在测试阶段使用test
和container-host-test
阶段来确保镜像快照或容器镜像在创建最终镜像AMI或分发容器镜像之前产生预期的结果。
当组件运行时,每个阶段的关联命令将按照它们在组件文档中出现的顺序进行应用。
阶段规则
-
每个阶段名称在文档中必须是唯一的。
-
您可以在文档中定义多个阶段。
-
您必须在文档中至少包含以下至少一个阶段:
-
构建 — 对于 Image Builder,此阶段通常在构建阶段使用。
-
验证 — 对于 Image Builder,此阶段通常在构建阶段使用。
-
测试 — 对于 Image Builder,此阶段通常在测试阶段使用。
-
-
阶段始终按照文档中定义的顺序运行。中为 AWSTOE 命令指定它们的顺序 AWS CLI 无效。
步骤
步骤是定义每个阶段中的工作流程的各个工作单元。步骤按先后顺序运行。但是,一个步骤的输入或输出也可以作为输入馈送到后续步骤中。这就是所谓的“链”。
步骤规则
-
步骤名称对于阶段来说必须是唯一的。
-
步骤必须使用可返回退出代码的支持的操作(操作模块)。
有关支持的操作模块、它们的工作方式、输入/输出值和示例的完整列表,请参阅 AWSTOE 组件管理器支持的操作模块。
组件日志
AWSTOE 每次组件运行时,都会在用于构建和测试新映像的EC2实例上创建一个新的日志文件夹。对于容器映像,日志文件夹存储在容器中。
为了帮助在图像创建过程中出现问题时进行故障排除,在运行组件时 AWSTOE 创建的输入文档和所有输出文件都存储在日志文件夹中。
日志文件夹名称由以下部分组成:
-
日志目录 — 当服务运行 AWSTOE 组件时,它会与该命令的其他设置一起传入日志目录。在以下示例中,我们展示了 Image Builder 使用的日志文件格式。
-
Linux:
/var/lib/amazon/toe/
-
Windows:
$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\
-
-
文件前缀 — 这是用于所有组件的标准前缀:“
TOE_
”。 -
运行时间 — 这是-MM-DD_HH YYYY-MM-SS_ -0 格式UTC的时间戳。
-
执行 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 、带有时间戳的调试级别信息,这些信息有关组件运行时发生的情况。
-
d@@ etailedoutput.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:
SampleS3Download
action: 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:
SamplePowerShellStep
action: 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:
文档的架构定义如下所示。
字段 | 描述 | 类型 | 必需 |
---|---|---|---|
name | 文档的名称。 | String | 否 |
description | 文档的描述。 | String |
否 |
schemaVersion | 文档的架构版本,当前为 1.0。 | String |
是 |
phases | 阶段及其步骤的列表。 |
列出 |
是 |
阶段的架构定义如下所示。
字段 | 描述 | 类型 | 必需 |
---|---|---|---|
name | 阶段的名称。 | String | 是 |
步骤 | 阶段中的步骤列表。 | 列出 |
是 |
步骤的架构定义如下所示。
字段 | 描述 | 类型 | 必需 | 默认值 |
---|---|---|---|---|
name | 用户定义的步骤名称。 | String | ||
action | 与运行步骤的模块相关的关键字。 | String | ||
timeoutSeconds |
在失败或重试之前,步骤运行的秒数。 此外,支持 -1 值,表示无限超时。不允许 0 和其他负值。 |
整数 |
否 |
7,200 秒(120 分钟) |
onFailure |
指定该步骤在失败时应执行的操作。有效值如下所示:
|
String |
否 |
中止 |
maxAttempts | 在步骤失败之前允许的最大尝试次数。 | 整数 |
否 |
1 |
inputs | 包含操作模块运行步骤所需的参数。 | 字典 |
是 |
文档示例架构
以下是一个示例文档架构,用于安装所有可用的 Windows 更新、运行配置脚本、在AMI创建之前验证更改,并在创建后测试更改。AMI
name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}'
以下是下载和运行自定义 Linux 二进制文件的示例文档架构。
name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://<replaceable>mybucket</replaceable>/<replaceable>myapplication</replaceable> destination: /tmp/<replaceable>myapplication</replaceable> - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}'
以下是使用安装文件在 Windows 实例 AWS CLI 上安装的示例文档架构。
name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}'
以下是 AWS CLI 使用安装MSI程序安装的示例文档架构。
name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}'