在中使用组件文档 EC2 TOE - EC2 Image Builder
组件文档工作流程组件日志输入和输出链文档架构和定义文档示例架构
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

在中使用组件文档 EC2 TOE

要使用 EC2 Task Orchestrator and Executor (EC2 TOE) 构建组件，必须提供一个基于 YAML 的文档，该文档表示适用于您创建的组件的阶段和步骤。 Amazon Web Services 当他们创建新的亚马逊系统映像 (AMI) 或容器映像时，请使用您的组件。

主题

组件文档工作流程

EC2 TOE 组件文档使用阶段和步骤对相关任务进行分组，并将这些任务组织成组件的逻辑工作流程。

提示

使用您的组件构建映像的服务可能会实施有关构建过程使用哪些阶段，以及何时允许这些阶段运行的规则。您在设计组件时，请务必考虑这一点。

阶段

阶段表示您的工作流程在映像构建过程中的进展。例如，Image Builder 服务在其构建阶段对其生成的映像使用 build 和 validate 阶段。它在测试阶段使用 test 和 container-host-test 阶段来确保在创建最终 AMI 或分发容器映像之前，映像快照或容器映像产生预期的结果。

当组件运行时，每个阶段的关联命令将按照它们在组件文档中出现的顺序进行应用。

阶段规则

  • 每个阶段名称在文档中必须是唯一的。

  • 您可以在文档中定义多个阶段。

  • 您必须在文档中至少包含以下至少一个阶段：

    • 构建 — 对于 Image Builder，此阶段通常在构建阶段使用。

    • 验证 — 对于 Image Builder，此阶段通常在构建阶段使用。

    • 测试 — 对于 Image Builder，此阶段通常在测试阶段使用。

  • 阶段始终按照文档中定义的顺序运行。中为 EC2 TOE 命令指定它们的顺序 Amazon CLI 无效。

步骤

步骤是定义每个阶段中的工作流程的各个工作单元。步骤按先后顺序运行。但是，一个步骤的输入或输出也可以作为输入馈送到后续步骤中。这就是所谓的“链”。

步骤规则

  • 步骤名称对于阶段来说必须是唯一的。

  • 步骤必须使用可返回退出代码的支持的操作（操作模块）。

    有关支持的操作模块、它们的工作方式、输入/输出值和示例的完整列表，请参阅 EC2 TOE 组件管理器支持的操作模块。

组件日志

EC2 TOE 每次运行组件时，都会在 EC2 实例上创建一个新的日志文件夹，用于构建和测试新映像。对于容器映像，日志文件夹存储在容器中。

为了帮助在图像创建过程中出现问题时进行故障排除，运行组件时 EC2 TOE 创建的输入文档和所有输出文件都存储在日志文件夹中。

日志文件夹名称由以下部分组成：

  1. 日志目录 — 当服务运行 EC2 TOE 组件时，它会与该命令的其他设置一起传入日志目录。在以下示例中，我们展示了 Image Builder 使用的日志文件格式。

    • Linux：/var/lib/amazon/toe/

    • Windows：$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\

  2. 文件前缀 — 这是用于所有组件的标准前缀：“TOE_”。

  3. 运行时间 — 这是 YYYY-MM-DD_HH-MM-SS_UTC-0 格式的时间戳。

  4. 执行 ID-这是 EC2 TOE 运行一个或多个组件时分配的 GUID。

例如：/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

EC2 TOE 在日志文件夹中存储以下核心文件：

输入文件

  • document.yaml — 用作命令输入的文档。组件运行后，该文件将作为构件存储。

输出文件

  • application.log — 应用程序日志包含来自 EC2 TOE 、带有时间戳的调试级别信息，这些信息有关组件运行时发生的情况。

  • detailedoutput.json — 此 JSON 文件包含有关组件运行时适用于组件的所有文档、阶段和步骤的运行状态、输入、输出和失败的详细信息。

  • console.log — 控制台日志包含组件运行时 EC2 TOE 写入控制台的所有标准输出 (stdout) 和标准错误 (stderr) 信息。

  • chaining.json — 此 JSON 文件表示 EC2 TOE 应用于解析链接表达式的优化。

注意

日志文件夹还可能包含此处未涵盖的其他临时文件。

输入和输出链

EC2 TOE 配置管理应用程序提供了一种通过编写以下格式的参考文献来链接输入和输出的功能：

{{ 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 文档的名称。 字符串 不支持
description 文档的描述。 字符串

不支持
schemaVersion 文档的架构版本，当前为 1.0。 字符串

支持
phases 阶段及其步骤的列表。

列出

支持

阶段的架构定义如下所示。

字段 描述 类型 必需
name 阶段的名称。 字符串 支持
步骤 阶段中的步骤列表。 列出

支持

步骤的架构定义如下所示。

字段 描述 类型 必需 默认值
name 用户定义的步骤名称。 字符串
action 与运行步骤的模块相关的关键字。 字符串
timeoutSeconds

在失败或重试之前，步骤运行的秒数。

此外，支持 -1 值，表示无限超时。不允许 0 和其他负值。

 整数

不支持

 7,200 秒（120 分钟）
onFailure

指定该步骤在失败时应执行的操作。有效值如下所示：

  • 中止 — 在达到最大尝试次数后该步骤失败，并停止运行。将阶段和文档的状态设置为 Failed。

  • 继续 — 在达到最大尝试次数后该步骤失败，并继续运行剩余的步骤。将阶段和文档的状态设置为 Failed。

  • 忽略 — 在达到最大失败尝试次数后将步骤设置为 IgnoredFailure，并继续运行剩余的步骤。将阶段和文档的状态设置为 SuccessWithIgnoredFailure。

字符串

不支持

 中止
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 实例 Amazon 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 }}'

以下是 Amazon 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 }}'