イメージビルドパイプラインが、Image Builder で「Step timed out while step is verifying the Systems Manager Agent availability on the target instance(s)」(ステップがターゲットインスタンスで Systems Manager Agent の可用性を検証している間に、ステップがタイムアウトしました) というエラーで失敗するのはなぜですか?

簡単な説明

EC2 Image Builder は AWS Systems Manager Automation を使用してカスタムイメージを構築します。イメージの構築とテストの実行に使用される Amazon EC2 インスタンスが AWS Systems Manager サービスにアクセスできることを確認します。

「failure message = 'Step timed out while step is verifying the SSM Agent availability on the target instance(s)」(エラーメッセージ = 'ステップがターゲットインスタンスで SSM Agent の可用性を確認している間に、ステップがタイムアウトしました) というエラーメッセージは、次の理由で発生する可能性があります。

• ビルドまたはテストインスタンスが Systems Manager エンドポイントにアクセスできない。この問題を解決するには、セキュリティグループとネットワークアクセスコントロールリスト (ネットワーク ACL) のインバウンドルールとアウトバウンドルールを確認します。
• インスタンスプロファイルに必要な許可がない。この問題を解決するには、インスタンスプロファイルに正しいポリシーがアタッチされていることを確認します。
• インスタンスが Instance Metadata Service (IMDS) に到達できない。この問題を解決するには、インスタンスが IMDS に到達できることを確認します。
• AWS Systems Manager Agent (SSM Agent) がベースイメージにインストールされていない。

解決方法

セキュリティグループとネットワーク ACL のアウトバウンドルールとインバウンドルールを確認する

ビルドインスタンスまたはテストインスタンスが Systems Manager エンドポイントにアクセスできない場合は、次を確認してください。

• セキュリティグループがポート 443 用にアウトバウンドを開いていること。
• ネットワーク ACL が、エフェメラルポート (1024–65535) 用にインバウンドを開いており、ポート 443 用にアウトバウンドを開いていること。

パブリックサブネットビルドの場合:

• サブネットでは、[Enable auto-assign public IPv4 address] (パブリック IPv4 アドレスの自動割り当てを有効化) がオンになっている必要があります。
• ルートテーブルには、インターネットゲートウェイがアタッチされている必要があります。

プライベートサブネットビルドの場合:

• ルートテーブルには、NAT ゲートウェイもしくはインスタンス、または Systems Manager (ssm、ssmmessages、ec2messages) および Image Builder への AWS PrivateLink エンドポイントのいずれかが必要です。ログ記録がオンになっている場合、ルートテーブルには Amazon Simple Storage Service (Amazon S3) または Amazon CloudWatch に対するエンドポイントも必要です。
• Amazon Virtual Private Cloud (Amazon VPC) エンドポイントのセキュリティグループは、ポート 443 で VPC CIDR へのインバウンドトラフィックを許可する必要があります。

インスタンスプロファイルに正しいポリシーがあることを確認する

インスタンスプロファイルは、インフラストラクチャ設定で定義されている AWS Identity and Access Management (IAM) ロールです。必要な許可がない場合、ビルドは失敗します。インスタンスプロファイルには、イメージを構築するための許可を持つ次のマネージドポリシーがアタッチされている必要があります。

• EC2InstanceProfileForImageBuilder
• EC2InstanceProfileForImageBuilderECRContainerBuilds (Docker イメージ用)
• AmazonSSMManagedInstanceCore

また、前のマネージドポリシーと類似の許可を持つカスタムポリシーを作成することもできます。

注: ロールの信頼ポリシーで、ec2.amazonaws.com がロールを引き受けることを許可されていることを確認してください。

インスタンスが IMDS に到達できることを確認する

IMDS は、実行中のインスタンスからメタデータにアクセスするために使用されます。インスタンスが IMDS に到達できない場合、ビルドは失敗します。インスタンスが IMDS に到達できるように、オペレーティングシステム (OS) のファイアウォールがポート 80 でトラフィック 169.254.169.254 を許可していることを確認してください。

次のコマンドを実行して接続をテストします。

$ telnet 169.254.169.254 80

プロキシを使用している場合は、プロキシと連携するように SSM Agent を設定します。Linux の場合は、「プロキシを使用するように SSM Agent を設定する (Linux)」を参照してください。Microsoft Windows の場合は、「SSM Agent が Windows Server インスタンス用にプロキシを使用するように設定する」を参照してください。

SSM Agent がベースイメージにインストールされていることを確認する

Image Builder がイメージの作成とテストの実行に使用するインスタンスには、Systems Manager Agent がインストールされている必要があります。

Linux

SSM Agent を持たない Amazon EC2 Linux インスタンスの場合、Image Builder はデフォルトでビルドインスタンスに SSM Agent をインストールします。ただし、レシピでユーザーデータを入力する場合は、SSM Agent が基本イメージにインストールされていることも確認する必要があります。または、ユーザーデータ入力を使用して SSM Agent をインストールします。

Windows

Image Builder は Windows Server 用の Amazon EC2 ビルドインスタンスに SSM Agent をインストールしません。SSM Agent がベースイメージにプレインストールされているかどうかを確認するには、ベースイメージを使用して EC2 インスタンスを起動します。その後、PowerShell で次のコマンドを実行します。

Get-Service AmazonSSMAgent

SSM Agent が基本イメージにプリインストールされていない場合は、ソースイメージからインスタンスを起動する必要があります。次に、EC2 インスタンスに SSM Agent を手動でインストールし、インスタンスから新しい基本イメージを作成します。

[Terminate instance on failure] (失敗時にインスタンスを終了) をオフにする

上記の解決策で問題が解決しない場合は、次を実行します。

1.    EC2 Image Builder コンソールを開きます。

2.    [Infrastructure configuration] (インフラストラクチャ設定)で、[Terminate instance on failure] (障害発生時にインスタンスを終了する) を有効にして、パイプラインを再実行します。

3.    インスタンスに接続し、次のコマンドを実行して Systems Manager エンドポイントへの接続を検証します。

Linux インスタンス

$ curl -v https://ssm.region.amazonaws.com

$ curl -v https://ec2messages.region.amazonaws.com

$ curl -v https://ssmmessages.region.amazonaws.com

Windows インスタンス

Test-NetConnection ssm.region.amazonaws.com -port 443

Test-NetConnection ec2messages.region.amazonaws.com -port 443

Test-NetConnection ssmmessages.region.amazonaws.com -port 443

注: region をご利用の AWS リージョンに置き換えます。

4.    次のパスを使用して、SSM ログに障害やエラーがないか確認します。

Linux

• /var/log/amazon/ssm/amazon-ssm-agent.log
• /var/log/amazon/ssm/errors.log

Windows

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

---