翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 失敗コンテキストで失敗したイメージビルドの原因を見つける
イメージビルドが失敗すると、Image Builder はイメージ で失敗を報告します`state`。状態には、 の障害と`reason`、 の構造化された**障害コンテキスト**を記述するメッセージが表示されます`failureContext`。
失敗コンテキストは、ワークフロー、ワークフローステップ、コンポーネントステップ、および失敗に関係する送信先リージョンに名前を付けるフィールドのセットです。フィールドは構造化されているため、自動化は直接分岐でき、その値を他の Image Builder API オペレーションに渡して詳細を確認できます。
Image Builder は、[GetImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html)、[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)、および [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html) API オペレーションから障害コンテキストを返し、Image Builder に表示します AWS マネジメントコンソール。
**Topics**
+ [失敗コンテキストに含まれる内容](#image-failure-context-fields)
+ [失敗したイメージの失敗コンテキストを表示する](#image-failure-context-view)
+ [根本原因への障害をトレースする](#image-failure-context-rca)
+ [AI エージェントで障害コンテキストを使用する](#image-failure-context-ai)
+ [考慮事項](#image-failure-context-considerations)
## 失敗コンテキストに含まれる内容
失敗コンテキストは、3 つのレベルで失敗を記述します。すべてのメンバーはオプションであり、Image Builder は失敗に適用されるメンバーのみを返します。メンバー、タイプ、および制約については、*EC2 * [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)」を参照してください。
イメージ
イメージが失敗したときのステージと、実行中のワークフローとワークフローステップ。ワークフローとステップの実行識別子は [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html) と [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html) と同じ値であるため、これらのオペレーションに直接渡すことができます。
コンポーネントステップ
コンポーネントによって発生したビルドまたはテストの失敗の場合、実行されたコンポーネント、ドキュメント内のフェーズとステップ、ステップが実行された AWSTOE アクションモジュール、ステップが報告したエラー。Image Builder はコンポーネントをビルドバージョンで識別するため、レシピがワイルドカードバージョンを参照している場合でも実行された正確なリビジョンに名前を付けます。アクションモジュールについては、「」を参照してください[AWSTOE コンポーネントマネージャーでサポートされるアクションモジュール](toe-action-modules.md)。
送信先リージョン
ディストリビューションまたは統合の失敗の場合、ディストリビューション全体のサマリーエラー、および失敗した送信先ごとに 1 つのエントリ。各エントリには、 、ディストリビューションの終了方法、Image Builder が呼び出したサービスのエラー、およびクロスアカウントディストリビューションの場合は Image Builder AWS アカウント がディストリビューションしたターゲットが保持されます。AMI コピーが成功したが、それに続くステップが成功しなかった場合、エントリはライセンス設定の関連付け、起動テンプレートの更新、SSM パラメータの設定、Amazon EC2 Fast Launch 設定の更新、AMI のエクスポートなど、そのステップにも名前を付けます。成功した送信先は省略されます。
**注記**
Image Builder が返すメンバーは、ビルドの進行状況によって異なります。Image Builder がワークフローを開始する前に発生する障害には、名前を付けるワークフローはありません。たとえば、レシピ内の親イメージが存在しなくなった場合、失敗コンテキストはステージを識別し、それ以上何も識別しません。
の例では、コンポーネント障害とディストリビューション障害に対して Image Builder が返すメンバー[失敗したイメージの失敗コンテキストを表示する](#image-failure-context-view)を示しています。
## 失敗したイメージの失敗コンテキストを表示する
**Image Builder コンソールで障害コンテキストを表示する**
Image Builder は、イメージのステータスを表示するたびに、`Failed`イメージの障害の詳細を表示します。
1. [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/) で、EC2 Image Builder コンソールを開きます。
1. ナビゲーションペインから**イメージ**を選択し、失敗したイメージビルドバージョンを選択します。パイプラインの**出力イメージ**リストを開くこともできます。
1. `Failed` イメージのステータスを選択します。Image Builder は、イメージの失敗の詳細を表示し、失敗したワークフローステップをランタイムの詳細にリンクします。
**で障害コンテキストを取得する AWS CLI**
失敗したイメージのビルドバージョン ARN を使用して **get-image** コマンドを実行します。
```
aws imagebuilder get-image \
--image-build-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0/1 \
--query "image.state"
```
次の出力例は、コンポーネントステップがゼロ以外のステータスで終了したスクリプトを実行したために失敗したビルドを示しています。
```
{
"status": "FAILED",
"reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
"failureContext": {
"imageStatus": "BUILDING",
"workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/{{x.x.x/x}}",
"stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"failedStep": "ApplyBuildComponents",
"componentFailure": {
"componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
"phaseName": "build",
"stepName": "InstallPackages",
"action": "ExecuteBash",
"errorMessage": "exit status 1"
}
}
}
```
次の出力例は、Image Builder が 3 つの送信先リージョンで起動テンプレートを更新している間に正常に構築およびテストされ、失敗したイメージを示しています。ビルドは他のすべての送信先で成功したため、失敗した 3 つのリージョンのみが表示されます。
```
{
"status": "FAILED",
"reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
"failureContext": {
"imageStatus": "INTEGRATING",
"distributionFailure": {
"errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
"regionFailures": [
{
"region": "eu-west-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
},
{
"region": "us-east-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
},
{
"region": "us-east-2",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
}
]
}
}
}
```
各ビルドを検査せずにアカウントで失敗したビルドを見つけるには、イメージビルドバージョンを一覧表示し、イメージのステータスをフィルタリングします。次の の例では、イメージの失敗したビルドと、それぞれの失敗コンテキストを返します。
```
aws imagebuilder list-image-build-versions \
--image-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0 \
--query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"
```
## 根本原因への障害をトレースする
失敗コンテキストは、失敗を 1 ステップに絞り込みます。次のステップを使用して、そのステップからそれを説明する証拠に移動します。
1. **`imageStatus`「」を読んで、失敗したステージを見つけます。**`BUILDING` または の値は、Image Builder が起動した Amazon EC2 インスタンスで障害が発生した`TESTING`ことを意味するため、コンポーネントログは次の場所です。`DISTRIBUTING` または の値は、イメージが構築され、障害がディストリビューション設定または送信先アカウントまたは にある`INTEGRATING`ことを意味します。
1. **特定の障害を説明するメンバーを読みます。**`componentFailure` が存在する場合、コンポーネントドキュメントの失敗ステップと、ステップが実行されたアクションと報告されたエラーを識別します。`distributionFailure` が存在する場合、 の各エントリは送信先と独自のエラー`regionFailures`を提供します。
1. **ワークフローランタイムの詳細を検査します。**で [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html) を呼び出し`workflowExecutionId`て、ワークフローのすべてのステップと、失敗したステップがシーケンス内のどこにあるかを確認します。失敗したステップ自体の入力、出力、ロールバックステータス`stepExecutionId`について、[GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html) を で呼び出します。
次の の例では、失敗したワークフロー実行のステップを一覧表示します。
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **失敗したステップのログを読み取ります。**`workflowExecutionId` および `failedStep`を使用して、そのステップのログパスに直接移動します。詳細については、「[ログから完全なコンポーネント出力を取得する](#image-failure-context-logs)」を参照してください。
1. **必要に応じて障害を再現します。**ビルドインスタンスを実行したままにして接続できるようにするには、パイプラインが使用するインフラストラクチャ設定の**障害時にインスタンスを終了する**設定をクリアします。詳細については、「[パイプラインビルドのトラブルシューティング](troubleshooting.md#troubleshooting-pipelines)」を参照してください。
### ログから完全なコンポーネント出力を取得する
失敗コンテキストは、コンポーネントステップで発生したエラーを報告しますが、ステップが実行されたスクリプトの標準出力と標準エラーは報告しません。Image Builder は、その出力をコンポーネントログに保持します。
コンポーネントが失敗すると、 は最初の失敗したステップの詳細をコンソールログに AWSTOE 書き込み、その後にそのステップの完全な標準エラー出力を書き込みます。
```
Document: MyExampleDocument
ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
Phase: build
Step: InstallPackages
Action: ExecuteBash
ErrorMessage: exit status 1
Stderr: {{the full standard error output of the step}}
```
`ComponentArn` は が`componentFailure.componentArn`報告するのと同じ値であるため、これを使用してログブロックをイメージの障害コンテキストと照合します。 `Document`は、コンポーネントドキュメント`name`が宣言する であり、作成者はコンポーネントリソースとは無関係に選択するため、2 つが異なり、`Document`単独ではどのコンポーネントが失敗したかを識別しません。
AWSTOE は、失敗したステップによって生成された`Stderr`場合にのみ `ErrorMessage`と を書き込みます。
Image Builder は、ビルドが完了するとコンポーネントログを Amazon CloudWatch Logs にストリーミングします。インフラストラクチャ設定で Amazon S3 バケットを指定した場合、Image Builder もバケットをそこに書き込みます。ロググループとストリーム名については、「」を参照してください[Amazon CloudWatch Logs を使用した Image Builder ログのモニタリング](monitor-cwlogs.md)。が AWSTOE 生成するファイルと各ファイルに含まれるファイルについては、「」を参照してください[コンポーネントロギング](toe-use-documents.md#component-logging)。
## AI エージェントで障害コンテキストを使用する
失敗コンテキストは、オートメーションとユーザーによって読み取られるように設計されています。失敗したビルドをトラブルシューティングする AI エージェントは、名前付きフィールドを読み取り、その値を次の API コールの引数として使用します。これにより、診断が繰り返し可能になり、エージェントが調査するコンポーネントや を推測できなくなります。
失敗コンテキストは、次のいずれかの方法で使用できます。
+ **Image Builder でのトラブルシューティング AWS マネジメントコンソール** – AWS DevOps Agent によるトラブルシューティング機能は、失敗コンテキストを使用して、ログと関連リソースを調べる前に失敗したワークフローステップとコンポーネントに調査の範囲を設定します。詳細については、「[AI を使用した失敗したビルドのトラブルシューティング - プレビュー](devops-agent-troubleshooting.md)」を参照してください。
+ **独自の AI コーディングエージェント** – を呼び出すエージェントは、レスポンスで障害コンテキスト`GetImage`を受け取り、同じ方法でそれに従うことができます。エージェントに Image Builder に関するより広範な知識を付与するには、「」を参照してください[AI コーディングエージェントを使用したビルドのトラブルシューティング](agent-toolkit-skill.md)。
失敗コンテキストに基づいて独自のオートメーションを構築する場合は、すべてのメンバーをオプションとして扱い、`failureContext`それ自体が存在するのではなく、使用するメンバーを確認します。Image Builder が返すメンバーは障害に応じて異なり、Image Builder は時間の経過とともにメンバーを追加できます。
## 考慮事項
失敗コンテキストを使用する場合は、次の点に注意してください。
+ Image Builder は、失敗したイメージに対してのみ失敗コンテキストを返します。成功したイメージとキャンセルしたイメージにはありません。
+ 失敗したイメージには、 `reason`と の両方が含まれます`failureContext`。失敗の読み取り可能な概要と、それを見つける`failureContext`ために `reason`を使用します。
+ コンポーネントが `ExecuteDocument`アクションを使用してネストされたドキュメントを実行する場合、障害コンテキストは、Image Builder がネストされたドキュメントではなくレシピから実行したコンポーネントを識別します。
+ 失敗コンテキストのエラーメッセージは長さに制限されており、切り捨てることができます。コンポーネントログは完全な出力を保持します。
+ 失敗コンテキストは、失敗した最初のステップを報告します。複数のステップが失敗した場合は、ワークフローステップの実行と残りのコンポーネントログを確認します。
+ エラーメッセージには、コンポーネントまたは別の AWS サービスが生成したテキストを含めることができます。レンダリングしたり、別のシステムに渡す場合は、信頼できない入力として扱います。