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

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

在中使用组件文档EC2 TOE

使用构建组件EC2 Task Orchestrator and Executor(EC2 TOE），您必须提供基于 YAML 的文档，该文档表示适用于您创建的组件的阶段和步骤。Amazon服务在创建新 Amazon 系统映像 (AMI) 或容器映像时使用您的组件。

主题

组件文档工作流

这些区域有：EC2 TOE组件文档使用阶段和步骤对相关任务进行分组，并将这些任务组织到组件的逻辑工作流中。每个组件都可以包含在映像构建过程中的任何阶段运行的阶段。

提示

使用组件构建映像的服务可能会实施有关构建过程使用哪些阶段的规则。在设计组件时，必须考虑这一点。

Phases

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

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

阶段规则

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

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

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

    • 构建— 通常在构建阶段.

    • 验证— 通常在构建阶段.

    • 测试— 通常在测试阶段.

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

Steps

步骤是定义每个阶段的工作流程的各个工作单元。步骤按先后顺序运行。但是，一个步骤的输入或输出也可以作为输入进入后续步骤。这被称为 “链接”。

步骤规则

  • 阶段的步骤名称必须是唯一的。

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

    有关支持的操作模块的完整列表、操作方式、输入/输出值以及示例，请参阅。支持的操作模块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. 运行时间— 这是 YYY-MM-D_HH-MM-SS_UTC-0 格式的时间戳。

  4. 执行 ID— 这是当时分配的 GUIDEC2 TOE运行一个或多个组件。

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

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

输入文件

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

输出文件

  • application.log— 应用程序日志包含来自的时间戳调试级别信息EC2 TOE关于组件运行时发生了什么。

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

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

  • 链接 .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:

文档的架构定义如下所示。

字段 描述 Type 必填
名称 文档的名称。 字符串 否
description 文档的描述。 字符串

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

是
phases 阶段及其步骤的列表。

List

是

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

字段 描述 Type 必填
名称 阶段的名称。 字符串 是
steps 阶段中的步骤列表。 List

是

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

字段 描述 Type 必填 默认值
名称 用户定义的步骤名称。 字符串
操作 与运行步骤的模块相关的关键字。 字符串

timeoutSeconds

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

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

 整数

是

 7,200 秒（120 分钟）
onFailure

指定在发生故障的情况下应该执行的步骤。有效值如下所示：

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

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

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

字符串

是

 Abort
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://mybucket/myapplication
            destination: /tmp/myapplication
      - 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 }}'

以下是一个示例文档架构，用于安装Amazon CLI使用安装文件。

name: InstallCLISetUp
description: Install Amazon 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 Amazon 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 }}'