EC2 Image Builder のビルドパイプラインタイムアウトエラーをトラブルシューティングする方法を教えてください。

所要時間2分

EC2 Image Builder のビルドパイプラインタイムアウトエラーをトラブルシューティングしたいです。

簡単な説明

LaunchBuildInstance、BootstrapBuildInstance、または ApplyBuildComponent の各ワークフローステップでステップタイムアウトエラーが発生して Image Builder ビルドパイプラインが失敗する一般的な理由には、次のようなものがあります。

ビルドインスタンスが AWS Systems Manager に接続できない。
AWS Identity and Access Management (IAM) ロールの権限に誤りがある。
プライベートサブネットがインターネットにアクセスできない。
ルートデバイス名の重複。

解決方法

ビルドパイプラインのタイムアウトエラーをトラブルシューティングするには、次のシナリオを参照してください。

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

ビルドがビルドインスタンスでの SSM Agent の可用性を検証しているときにタイムアウトが発生する

ビルドがビルドインスタンスの AWS Systems Manager Agent を検証しているときにビルドパイプラインのタイムアウトが発生すると、次のエラーが表示されることがあります。

「ワークフロー実行 ID: が失敗しました。理由: ワークフローステップ LaunchBuildInstance で、ExpectationNotMet. ssm:*CommandInvocations がターミナル状態 Failed を返しました。」

「ワークフロー実行 ID: が失敗しました。理由: SendCommand オペレーションの呼び出し時に、エラー InvalidInstanceId が発生しました: インスタンス [[i-1a1b1c1d1e1f1g1h1]] は、ワークフローステップ LaunchBuildInstance のアカウントに対して有効な状態ではありません。」

「ワークフロー実行 ID: が失敗しました。理由: ExpectationNotMet (期待値が満たされていません)。ec2: DescribeInstanceStatus が 100 回試行してもターミナル状態 [['passed']] を満たしませんでした。理由: ワークフローステップで LaunchBuildInstance でタイムアウトが発生しました。」

これらのビルドパイプラインタイムアウトエラーは、インスタンスのパイプラインインフラストラクチャロールに必要な IAM アクセス許可がない場合に発生します。これらのエラーは、SSM エージェントがエンドポイントに到達できる場合にも発生します。

**インスタンスに必要な IAM アクセス許可がありません **

ビルドインスタンスに必要な IAM アクセス許可がない場合は、マネージドポリシー AmazonSSMManagedInstanceCore を IAM ロールに追加します。IAM ロールは、Image Builder インフラストラクチャ設定で指定します。また、AWSServiceRoleForImageBuilder ロールが AWS Key Management Service (AWS KMS) キーを使用できることを確認してください。このロールには、イメージレシピブロックデバイスで指定されている AWS KMS キーへのアクセス権限が必要です。詳細については、「キーユーザーに KMS キーの使用を許可する」を参照してください。

SSM エージェントがエンドポイントに到達できない

SSM Agent がエンドポイントに到達できない場合は、次のアクションを実行してください。

インターネットゲートウェイを使用してパブリックサブネットを構築する場合は、パブリック IPv4 アドレスを自動的に割り当てるようにサブネットを構成します。
NAT を使用してプライベートサブネットを構築する場合は、パブリックサブネットを使用するように NAT を設定します。
Amazon Virtual Private Cloud (Amazon VPC) エンドポイントを使用してプライベートサブネットを構築する場合は、システムマネージャーに AWS PrivateLink エンドポイントを設定します。詳細については、「インターネットにアクセスしなくても、VPC エンドポイントを作成して Systems Manager でプライベート EC2 インスタンスを管理する方法を教えてください。」を参照してください。
セキュリティグループとネットワークアクセスコントロールリスト (ネットワーク ACL) がエフェメラルポート (1024～65535) のインバウンド接続を許可していることを確認します。また、ポート 443 でのアウトバウンド接続を許可する必要があります。PrivateLink エンドポイントがあるプライベートサブネットの場合、Amazon VPC エンドポイントにアタッチされているセキュリティグループがポート 443 でのインバウンド接続を許可する必要があります。これらのインバウンド接続は、サブネットまたは Amazon VPC の CIDR アドレスからの許可が必要です。

ビルドが AWS CLI をダウンロードするときにタイムアウトが発生する

プライベートサブネット上でビルドするときに、aws-cli-version-2-linux または aws-cli-version-2-windows コンポーネントのいずれかを使用している場合、ApplyBuildComponents ステップでビルドタイムアウトが発生することがあります。

コンテナビルドの場合、BootstrapBuildInstance ステップでビルドタイムアウトが発生する場合があります。タイムアウトは、インスタンスの AMI に AWS CLI が存在せず、ブートストラップスクリプトがインターネット経由で AWS CLI をインストールしようとした場合に発生します。

このタイムアウトを解決するには、次の操作を行います。

NAT ゲートウェイまたはインターネットゲートウェイを介したサブネットのインターネット接続を許可します。
AWS CLI がインストールされたカスタム AMI を使用します。

ルートデバイス名が重複している場合、タイムアウトが発生します

CreateImageRecipe API を使用してレシピを作成する際に、ルートデバイスに /dev/xvda または /dev/sda1 という名前を付けると、エラーが発生する場合があります。ビルドインスタンスでルートデバイス名が重複しないようにするには、ソース AMI のルートデバイスマッピングを確認してください。ルートデバイス名が重複している場合、次のエラーが表示され、タイムアウトが発生します。

注:AWS マネジメントコンソールのイメージレシピを使用する場合、重複するデバイス名を作成することはできません。また、AWS Nitro System インスタンスタイプ (もしくは Xen インスタンスタイプ) は、デバイス名の重複が原因で障害が発生しない唯一のインスタンスタイプです。

AMI のルートデバイスの場合は、describe-images コマンドを実行してソース AMI のデバイス名を確認します。イメージレシピと同じデバイス名を使用してください。

ビルドが Image Builder コンポーネントを取得しているときにタイムアウトが発生する

プライベートサブネット上にビルドしていて、コンポーネントのダウンロード時に Image Builder が失敗すると、次のエラーが表示されます。

「EC2 Image Builder コンポーネントのダウンロードに失敗しました。オペレーションエラー imagebuilder: GetComponent。最大試行回数 3 回を超えました。ダイヤル TCP 入出力のタイムアウト発生。」

上記のエラーを解決するには、設定を確認してください。または、Image Builder インフラストラクチャ設定で使用されているものと同じ VPC とサブネットにインターフェイス Amazon VPC エンドポイントが存在しない場合は、作成します。

ビルドがミラーリストを取得したときにタイムアウトが発生する

Amazon Linux ベースの AMI を使用してプライベートサブネット上にビルドすると、次のタイムアウトエラーが発生することがあります。

「ミラーリストを取得できませんでした。エラー 12: タイムアウトに達しました。」

Amazon Linux ミラーリストは、Amazon Simple Storage Service (Amazon S3) に保存されます。Amazon S3 の Amazon VPC ゲートウェイエンドポイントが存在することを確認します。または、Amazon VPC ゲートウェイエンドポイントを作成します。Amazon S3 プレフィックスリストは、エンドポイントを作成するときに自動的にルートテーブルに追加されます。ただし、ベストプラクティスとして、プレフィックスリストが追加されていることを確認してください。

Amazon Linux 以外の AMI でビルドしている場合、ミラーリストは Amazon S3 に保存されません。ビルドがリポジトリ/ミラーリストを取得しているときにも、ビルドタイムアウトが発生する場合があります。リポジトリアドレスや URL を、ネットワークファイアウォールやプロキシに許可していることを確認してください。リポジトリ/ミラーリストにインターネットが必要な場合は、サブネットで NAT ゲートウェイ経由のインターネット接続を許可します。

タイムアウトは ApplyBuildComponents ステップで発生します。

ApplyBuildComponents ステップでビルドタイムアウトが発生すると、次のエラーが表示されます。

「ワークフロー実行 ID: が失敗しました。理由: ExpectationNotMet (期待値が満たされていません)。ssm:ListCommandInvocations は、1440 回試行してもターミナル状態:\ [\ ['Success']] を満たしませんでした。理由: ワークフローステップ ApplyBuildComponents でタイムアウトが発生しました。」

このエラーをトラブルシューティングするには、次のアクションを実行してください。

インフラストラクチャの Amazon S3 バケットに送信されるログを分析します。詳細については、「パイプラインビルドのトラブルシューティング」の「ワークフローランタイムログの確認」セクションで、Amazon Simple Storage Service (Amazon S3) の箇条書き項目を参照してください。
新しいイメージの構築またはテストに使用する Amazon Elastic Compute Cloud (Amazon EC2) インスタンスにある、コンポーネントログを分析します。ログを確認する前に、インフラストラクチャ設定のトラブルシューティングセッションで、障害発生時にインスタンスを終了する機能をオフにしてください。
注: detailedoutput.json ログファイルには、コンポーネントが失敗またはタイムアウトした理由が記載されています。application.log ファイルには、デバッグレベルのトラブルシューティング情報が記載されています。
ドキュメントの YAML スキーマに指定されている timeoutSeconds パラメータ値を確認してください。デフォルト値は 7200 です。必要に応じて、コンポーネントの各ステップでこの値を更新します。\ -1 の値は無限を表します。