EC2 Image Builder パイプラインの障害をトラブルシューティングする方法を教えてください。

所要時間2分

EC2 Image Builder パイプラインの障害をトラブルシューティングしたいです。

簡単な説明

Image Builder のパイプラインで障害が発生すると、ワークフローの実行 ID を返し、パイプラインで障害が発生した理由を説明するエラーが表示されます。

「ワークフロー実行 ID: example-workflow-id が失敗しました。理由: example-reason」

プロセスの各ビルドおよびテストステージには、関連するワークフローがあります。 コンテナイメージには、ディストリビューション中に実行される追加のワークフローがあります。また、各ワークフローには、高品質の Amazon マシンイメージを構築するために必要なステップがあります。

解決策

**注:**AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI エラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

Image Builder パイプラインの障害をトラブルシューティングするには、次の手順を実行します。

パイプライン障害の原因となったワークフローのステージとステップを確認する

パイプライン障害の原因となったワークフローのステージとステップを確認するには、次のいずれかの方法を使用します。

API を使用する
パイプライン障害の原因となったワークフローステージとステップを確認するには、ワークフロー実行 ID を指定して GetWorkflowExecution と ListWorkflowStepExecution API コマンドを使用します。

AWS マネジメントコンソールを使用する
AWS マネジメントコンソールを使用して、パイプライン障害の原因となったワークフローのステージとステップを確認するには、次のステップを実行します。

Image Builder コンソールを開きます。
左側のペインで [イメージパイプライン] を選択します。次に、パイプラインを選択します。
[出力イメージ] で、障害が発生した出力イメージバージョンを選択します。
[ワークフロー] で、ワークフローのドロップダウンリストを選択し、障害が発生したステージを選択します。障害が発生したステージに関するステップのリストが表示されます。

パイプライン障害の原因となったワークフローのステージとステップを特定したら、次の方法を使用してさらにトラブルシューティングを行います。

CloudWatch ログに送信されるログを確認する

Image Builder が詳細なワークフローログを /aws/ImageBuilder/ImageName ロググループと ImageVersion/ImageBuildVersion ログストリームに公開しました。これらのログストリームは、Amazon CloudWatch コンソールまたは Image Builder コンソールから確認できます。

Image Builder コンソールで CloudWatch Logs に送信されたログを確認するには、次の手順を実行します。

Image Builder コンソールを開きます。
左側のペインで [イメージパイプライン] を選択します。次に、パイプラインを選択します。
[出力イメージ] で、障害が発生した出力イメージバージョンを選択します。
[ワークフロー] で、ワークフローのドロップダウンリストを選択し、障害が発生したステージを選択します。
障害が発生したステップのステップ ID を選択します。
[アプリケーションログ] を選択します。
さらにトラブルシューティングを行うために、アプリケーションログを確認します。

注: 前の手順を完了しても問題をトラブルシューティングできない場合は、次の方法に進んでください。

Amazon S3 に送信されたログを確認する

Amazon Simple Storage Service (Amazon S3) ログは、ビルドプロセス中の Amazon Elastic Compute Cloud (Amazon EC2) インスタンスアクティビティに関するステップとエラーを示します。Amazon S3 ログには、コンポーネントマネージャーからのログ出力である、コンポーネント定義が含まれます。これらのログには、Amazon EC2 インスタンスで実行されたステップの詳細な JSON 出力が含まれます。

インフラストラクチャ設定で Amazon S3 バケット名とキープレフィックスを指定した場合、ワークフローステップのログパスは S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName になります。

Amazon S3 バケット名とキープレフィックスを指定しなかった場合は、Image Builder コンソールを開き、トラブルシューティング設定に移動します。次に [ログ] で、Image Builder がログを書き込むことができる Amazon S3 バケットを指定します。Amazon S3 バケットを指定したら、パイプラインを再度実行してログを収集し、バケットに保存します。

Amazon EC2 インスタンスのログを確認する

AWS Task Orchestrator and Executor (AWSTOE) のコンポーネントマネージャーが、新しいイメージの構築とテストに使用するログフォルダをインスタンス上に作成します。これらのログフォルダは、コンポーネントを実行するたびに作成されます。コンテナイメージの場合、ログフォルダーはコンテナーに保存されます。

注: デフォルトでは、パイプラインのビルドが失敗すると、Image Builder はビルドまたはテストインスタンスをシャットダウンします。トラブルシューティングを行うためにビルドまたはテストインスタンスを保持するには、パイプラインのインフラストラクチャ設定リソースのインスタンス設定を変更します。インスタンス設定を変更するには、Image Builder コンソールを開き、インフラストラクチャ設定リソースのトラブルシューティング設定に移動します。次に、[障害発生時にインスタンスを終了] オプションを無効にします。

update-infrastructure-configuration コマンドを使用してインスタンスの設定を変更することもできます。TerminateInstanceOnFailure の値は、false に設定してください。詳細については、「インフラストラクチャ構成の更新」を参照してください。

ビルドまたはテストインスタンスに接続し、次の場所でランタイムログを探します。

Linux の場合は、/var/lib/amazon/toe/file_prefix_runtime_ExecutionID ディレクトリを確認します。
Windows の場合は、env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\file_prefix_run time_executionID ディレクトリを確認します。

ログファイルの例: /var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

前述のログディレクトリで、パイプライン障害のトラブルシューティングをさらに行うには、以下のファイルを確認してください。

application.log - コンポーネントの実行時に発生するアクティビティに関連する、AWSTOE からのタイムスタンプ付きデバッグレベルの情報が含まれます。
detailedoutput.json - コンポーネントの実行時に適用されるすべてのドキュメント、フェーズ、ステップに関する実行ステータス、入力、出力、失敗についての詳細情報が含まれます。
console.log - コンポーネントの実行時に AWSTOE がコンソールに書き込む標準出力 (stdout) および標準エラー (stderr) 情報が含まれます。
chaining.json - AWSTOE が連鎖式を解決するために適用する最適化を表します。

CloudTrail のイベントをチェックする

アカウントで AWS CloudTrail が有効になっている場合、すべてのビルドアクティビティがログに記録されます。CloudTrail イベントをフィルター処理するには、source: imagebuilder.amazonaws.com、username: Image Builder でフィルター処理するか、関連する Amazon EC2 インスタンス ID を検索します。これらのフィルターは、パイプラインに関する詳細を示すログを返します。

ディストリビューションプロセス中の API トレイルをトラブルシューティングするには、CloudTrail イベントを、username: Ec2ImageBuilderIntegrationService でフィルター処理すると、ディストリビューションプロセス中の API トレイルをトラブルシューティングできます。このメソッドを使用して、Image Builder が実行し、失敗した API 呼び出しに関する情報を取得します。