でコンポーネントドキュメントを使用する AWSTOE - EC2 Image Builder
コンポーネントドキュメントワークフローコンポーネントロギング入力チェーンと出力連鎖文書スキーマと定義文書例のスキーマ

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

でコンポーネントドキュメントを使用する AWSTOE

AWS Task Orchestrator and Executor (AWSTOE) を使用してコンポーネントを構築するには、作成するコンポーネントに適用されるフェーズと手順を表す YAML ベースのドキュメントを提供する必要があります。 AWS のサービス 新しい Amazon マシンイメージ (AMI) またはコンテナイメージを作成するときには、コンポーネントを使用してください。

トピック

コンポーネントドキュメントワークフロー

AWSTOE コンポーネントドキュメントでは、フェーズとステップを使用して関連するタスクをグループ化し、それらのタスクをコンポーネントの論理的なワークフローにまとめます。

ヒント

コンポーネントを使用してイメージを構築するサービスには、ビルドプロセスにどのフェーズを使用するか、またそれらのフェーズをいつ実行できるかについてのルールが実装されている場合があります。これはコンポーネントを設計する際に考慮すべき重要な点です。

phases

フェーズは、イメージビルドプロセスにおけるワークフローの進行状況を表します。たとえば、Image Builder サービスは、生成するイメージのビルド段階でbuildとvalidateのフェーズを使用します。テスト段階ではtestとcontainer-host-testフェーズを使用して、イメージスナップショットまたはコンテナイメージが期待どおりの結果を生成することを確認してから、最終的な AMI を作成するか、コンテナイメージを配布します。

コンポーネントが実行されると、各フェーズの関連コマンドがコンポーネントドキュメントに表示されている順序で適用されます。

フェーズのルール

  • フェーズ名はドキュメント内で一意である必要があります。

  • 文書には多数のフェーズを定義できます。

  • ドキュメントには、次のうち、少なくとも 1 つは指定が必要です。

    • ビルド — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。

    • 検証 — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。

    • テスト — Image Builder の場合、このフェーズは通常、テスト段階で使用されます。

  • フェーズは、常にドキュメントで定義されている順序で実行されます。 AWSTOE AWS CLI 内のコマンドに指定されている順序は影響しません。

ステップ

ステップは、各フェーズ内のワークフローを定義する個別の作業単位です。ステップは順番に実行されます。ただし、あるステップのインプットまたはアウトプットを、インプットとして後続のステップに送ることもあります。これをロールの連鎖と呼びます。

ステップのルール

  • その名前はボットに対して一意である必要があります。

  • ステップでは、終了コードを返すサポートされているアクション (アクションモジュール) を使用する必要があります。

    サポートされているアクションモジュールの全リスト、その仕組み、入出力値、例については、AWSTOE コンポーネントマネージャーがサポートするアクションモジュールを参照してください。

コンポーネントロギング

AWSTOE コンポーネントを実行するたびに、新しいイメージの構築とテストに使用される新しいログフォルダが EC2 インスタンスに作成されます。コンテナイメージの場合、ログフォルダはコンテナに保存されます。

イメージ作成プロセス中に問題が発生した場合のトラブルシューティングに役立つように、 AWSTOE コンポーネントの実行中に作成された入力ドキュメントとすべての出力ファイルはログフォルダに保存されます。

ログフォルダー名は次の部分で構成されています。

  1. ログディレクトリ — AWSTOE サービスがコンポーネントを実行すると、コマンドの他の設定とともにログディレクトリに渡されます。以下の例では、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 — 1 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 }}'

  • 連鎖式は同じドキュメント内の他のステップやフェーズの変数を参照できます。ただし、呼び出し元のサービスには、連鎖式を 1 つのステージのコンテキスト内でのみ動作させることを要求するルールがある場合があります。たとえば、Image Builder は各ステージを独立して実行するため、ビルドステージからテストステージへのチェーニングをサポートしていません。

  • 連鎖式のインデックスは 0 から始まるインデックスに従います。インデックスは最初の要素を参照するゼロ (0) から始まります。

例

次のサンプルステップの 2 番目のエントリでソース変数を参照する場合、チェーンパターンは{{ 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 文書の名前 文字列 いいえ
説明 文書の説明 文字列

いいえ
schemaVersion ドキュメントのスキーマバージョン。現在は 1.0。 文字列

はい
phases フェーズとそのステップのリスト。

リスト

はい

フェーズのスキーマ定義は次のとおりです。

フィールド 説明 タイプ 必須
name フェーズの名前 文字列 はい
steps フェーズ内のステップのリスト。 リスト

はい

ステップのスキーマ定義は次のとおりです。

フィールド 説明 タイプ 必須 デフォルト値
name ステップのユーザー定義名。 文字列
アクション ステップを実行するモジュールに関するキーワード。 文字列
timeoutSeconds

ステップが失敗または再試行されるまでに実行される秒数。

また、タイムアウトが無限であることを示す -1 値もサポートします。0 やその他の負の値は使用できません。

 整数

いいえ

 7,200 秒 (120 分)
onFailure

ステップが失敗した場合は実行する内容を指定します。有効な値は次のとおりです。

  • 中止 — 最大回数試行するとステップが失敗し、実行を停止します。フェーズとドキュメントのステータスをFailedに設定します。

  • 続行 — 最大回数試行するとステップが失敗し、残りのステップの実行を継続します。フェーズとドキュメントのステータスをFailedに設定します。

  • 無視 — 試行に失敗した回数が最大回数を超えた後IgnoredFailureにステップを設定し、残りのステップを引き続き実行します。フェーズとドキュメントのステータスをSuccessWithIgnoredFailureに設定します。

文字列

いいえ

 中止
maxAttempts ステップが失敗するまでに許可される最大試行回数。 整数

いいえ

 1
入力 アクションモジュールがステップを実行するのに必要なパラメータが含まれます。 dict

はい

文書例のスキーマ

以下は、使用可能なすべての 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 }}'

MSI AWS CLI インストーラを使用してをインストールするドキュメントスキーマの例を次に示します。

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 }}'