翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# カスタム AWSTOE コンポーネントのコンポーネントドキュメントフレームワークを使用する
AWS Task Orchestrator and Executor (AWSTOE) コンポーネントフレームワークを使用してコンポーネントを構築するには、作成したコンポーネントに適用されるフェーズとステップを表す YAML ベースのドキュメントを提供する必要があります。コンポーネントは、新しい Amazon マシンイメージ (AMI) またはコンテナイメージを作成するときに AWS のサービス 使用します。
**Topics**
+ [コンポーネントドキュメントワークフロー](#component-doc-workflow)
+ [コンポーネントロギング](#component-logging)
+ [入力チェーンと出力連鎖](#document-chaining)
+ [文書スキーマと定義](#document-schema)
+ [ドキュメントの例](#document-example)
+ [カスタムコンポーネントドキュメントでの変数の使用](toe-user-defined-variables.md)
+ [で条件付きコンストラクトを使用する AWSTOE](toe-conditional-constructs.md)
+ [AWSTOE コンポーネントドキュメントで比較演算子を使用する](toe-comparison-operators.md)
+ [AWSTOE コンポーネントドキュメントで論理演算子を使用する](toe-logical-operators.md)
+ [でループコンストラクトを使用する AWSTOE](toe-looping-constructs.md)
## コンポーネントドキュメントワークフロー
AWSTOE コンポーネントドキュメントでは、フェーズとステップを使用して関連タスクをグループ化し、それらのタスクをコンポーネントの論理ワークフローに整理します。
**ヒント**
コンポーネントを使用してイメージを構築するサービスには、ビルドプロセスにどのフェーズを使用するか、またそれらのフェーズをいつ実行できるかについてのルールが実装されている場合があります。これはコンポーネントを設計する際に考慮すべき重要な点です。
**phases**
フェーズは、イメージビルドプロセスにおけるワークフローの進行状況を表します。例えば、Image Builder サービスは、生成するイメージのビルド段階で `build` と `validate` のフェーズを使用します。*テスト段階*では `test` と `container-host-test` フェーズを使用して、イメージスナップショットまたはコンテナイメージが期待どおりの結果を生成することを確認してから、最終的な AMI を作成するか、コンテナイメージを配布します。
コンポーネントが実行されると、各フェーズの関連コマンドがコンポーネントドキュメントに表示されている順序で適用されます。
**フェーズのルール**
+ フェーズ名はドキュメント内で一意である必要があります。
+ 文書には多数のフェーズを定義できます。
+ ドキュメントには、次のうち、少なくとも 1 つは指定が必要です。
+ **ビルド** — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。
+ **検証** — Image Builder の場合、このフェーズは通常、ビルド段階で使用されます。
+ **テスト** — Image Builder の場合、このフェーズは通常、テスト段階で使用されます。
+ フェーズは、常にドキュメントで定義されている順序で実行されます。で AWSTOE AWS CLI コマンドに指定された順序は効果がありません。
**Steps**
ステップは、各フェーズ内のワークフローを定義する個別の作業単位です。ステップは順番に実行されます。ただし、あるステップのインプットまたはアウトプットを、インプットとして後続のステップに送ることもあります。これをロールの連鎖と呼びます。
**ステップのルール**
+ その名前はボットに対して一意である必要があります。
+ ステップでは、終了コードを返すサポートされているアクション (アクションモジュール) を使用する必要があります。
サポートされているアクションモジュールの全リスト、その仕組み、入出力値、例については、[AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール](toe-action-modules.md) を参照してください。
## コンポーネントロギング
AWSTOE は、コンポーネントが実行されるたびに、新しいイメージの構築とテストに使用される新しいログフォルダを EC2 インスタンスに作成します。コンテナイメージの場合、ログフォルダはコンテナに保存されます。
イメージ作成プロセス中に問題が発生した場合のトラブルシューティングを支援するために、コンポーネントの実行中に AWSTOE が作成する入力ドキュメントとすべての出力ファイルはログフォルダに保存されます。
ログフォルダ名は次の部分で構成されています。
1. **ログディレクトリ** – サービスが AWSTOE コンポーネントを実行すると、コマンドの他の設定とともにログディレクトリに渡されます。以下の例では、Image Builder が使用するログファイル形式を示します。
+ **Linux および macOS**: `/var/lib/amazon/toe/`
+ **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\`
1. **ファイルプレフィックス** — "`TOE_`" これはすべてのコンポーネントに使用される標準のプレフィックスです。
1. **ランタイム** — これは YYYY-MM-DD\_HH-MM-SS\_UTC-0 形式のタイムスタンプです。
1. **実行 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:
```
ドキュメントのスキーマ定義は次のとおりです。
| フィールド | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| 名前 | 文書の名前。 | String | いいえ |
| 説明 | 文書の説明。 | String | いいえ |
| schemaVersion | ドキュメントのスキーマバージョン。現在は 1.0。 | String | はい |
| phases | フェーズとそのステップのリスト。 | リスト | はい |
フェーズのスキーマ定義は次のとおりです。
| フィールド | 説明 | タイプ | 必須 |
| --- | --- | --- | --- |
| 名前 | フェーズの名前。 | String | はい |
| ステップ | フェーズ内のステップのリスト。 | リスト | はい |
ステップのスキーマ定義は次のとおりです。
| フィールド | 説明 | タイプ | 必須 | デフォルトの値 |
| --- | --- | --- | --- | --- |
| 名前 | ステップのユーザー定義名。 | String | | |
| アクション | ステップを実行するモジュールに関するキーワード。 | String | | |
| timeoutSeconds | ステップが失敗または再試行されるまでに実行される秒数。
また、タイムアウトが無限であることを示す -1 値もサポートします。0 やその他の負の値は使用できません。 | 整数 | いいえ | 7,200 秒 (120 分) |
| onFailure | ステップが失敗した場合は実行する内容を指定します。有効な値は次のとおりです。[See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/imagebuilder/latest/userguide/toe-use-documents.html) | String | いいえ | 中止 |
| maxAttempts | ステップが失敗するまでに許可される最大試行回数。 | 整数 | いいえ | 1 |
| 入力 | アクションモジュールがステップを実行するのに必要なパラメータが含まれます。 | dict | はい | |
## ドキュメントの例
次の例は、ターゲットオペレーティングシステムのタスクを実行する AWSTOE コンポーネントドキュメントを示しています。
------
#### [ Linux ]
**例 1: カスタムバイナリファイルを実行する**
以下は、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://amzn-s3-demo-source-bucket/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 }}'
```
------
#### [ Windows ]
**例 1: Windows 更新プログラムをインストールする**
次のドキュメントの例では、利用可能な 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}}'
```
**例 2: Windows インスタンス AWS CLI に をインストールする**
セットアップファイルを使用して 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 }}'
```
**例 3: MSI インストーラ AWS CLI を使用して をインストールする**
以下は、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 }}'
```
------
#### [ macOS ]
**例 1: カスタム macOS バイナリファイルを実行する**
次のドキュメントの例では、macOS インスタンスにカスタムバイナリファイルをダウンロードして実行します。
```
name: macOSBin
description: Download and run a binary file on macOS.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: Download
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/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 }}'
```
------