SSM Agent ログを使用してマネージドインスタンスの SSM Agent に関する問題をトラブルシューティングするにはどうすればよいですか?

最終更新日: 2022 年 4 月 14 日

AWS Systems Manager Agent (SSM Agent) が正常に実行されず、SSM Agent ログを使用して問題をトラブルシューティングする方法がわかりません。SSM Agent のログメッセージにアクセスし、これを解釈するにはどうすればよいですか?

簡単な説明

SSM Agent は、マネージド Amazon Elastic Compute Cloud (Amazon EC2) インスタンスで実行され、AWS Systems Manager サービスからのリクエストを処理します。SSM Agent を使用するには、次の条件を満たす必要があります。

  • SSM Agent は、必要なサービスエンドポイントに接続する必要があります。
  • SSM Agent では、Systems Manager API 呼び出しを行うための AWS Identity and Access Management (IAM) アクセス許可が必要です。

これらの条件のいずれかが満たされない場合、SSM Agent が正常に実行されません。

SSM Agent のエラーの根本原因を特定するには、次の場所で SSM Agent のログを確認します。

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

注: SSM Agent は新機能のリリースに伴って頻繁に更新されるため、SSM Agent の自動更新を設定することをお勧めします。

解決方法

ログを確認し、SSM Agent の問題がエンドポイント接続またはアクセス許可の不足が原因かどうかを確認した後、次のトラブルシューティング手順を実行します。

SSM Agent が必要なエンドポイントと通信できない

SSM Agent がメタデータサービスにアクセスできない

SSM Agent がメタデータサービスに到達できないため、SSM Agent はインスタンスメタデータサービスからリージョン情報、IAM ロール、およびインスタンス ID を特定できません。SSM Agent がメタデータサービスのエンドポイントに到達できないと、SSM Agent のログに次のようなエラーメッセージが表示されます。

INFO- インスタンス ID を取得できませんでした。ボールトからのデータは空です。RequestError: 次が原因でリクエストの送信に失敗しました: Get http://169.254.169.254/latest/meta-data/instance-id

このエラーの最も一般的な理由は、プロキシを使用するように SSM Agent を設定せずに、プロキシを使用してインスタンスからアウトバウンドインターネット接続を作成することです。プロキシを使用するように SSM Agent を設定してください。

Windows インスタンスでは、カスタム AMI を使用してインスタンスを起動する際に、永続的なネットワークルートが正しく設定されていないことが原因でエラーが発生することもあります。メタデータサービス IP のルートが正しいデフォルトゲートウェイをポイントしていることを確認する必要があります。

SSM Agent が Systems Manager のサービスエンドポイントに到達できない

SSM Agent は、ポート 443 で次の Systems Manager サービス API コールとのアウトバウンド接続を確立する必要があります。接続が確立されていない場合、SSM Agent は正しく機能しません。

  • SSM エンドポイント: ssm.REGION.amazonaws.com
  • EC2 メッセージングエンドポイント: ec2messages.REGION.amazonaws.com
  • SSM メッセージングエンドポイント: ssmmessages.REGION.amazonaws.com

: SSM Agent は、インスタンスメタデータサービスによって取得されたリージョン情報を使用して、上記のエンドポイントの REGION 値を置き換えます。

SSM Agent が Systems Manager エンドポイントに接続できない場合、SSM Agent ログに次のようなエラーメッセージが表示されます。

AWS API を呼び出すときの ERROR [HealthCheck] エラー。エラーの詳細 - RequestError: 次が原因でリクエストの送信に失敗しました: Post https://ssm.ap-southeast-2.amazonaws.com/: dial tcp 172.31.24.65:443: i/o タイムアウト
DEBUG [MessagingDeliveryService] RequestError: リクエストの送信に失敗しました
原因: Post https://ec2messages.ap-southeast-2.amazonaws.com/: net/http: 接続の待機中にリクエストがキャンセルされました (ヘッダーの待機中に Client.Timeout を超過しました)

SSM Agent がポート 443 で Systems Manager API エンドポイントに接続できない一般的な理由をいくつか次に示します。

  • インスタンスエグレスセキュリティグループのルールが、ポート 443 でのアウトバウンド接続を許可していない。
  • 仮想プライベートクラウド (VPC) エンドポイントのイングレスおよびエグレスセキュリティグループルールが、ポート 443 における VPC インターフェイスエンドポイントへの着信および発信接続を許可していない。
  • インスタンスがパブリックサブネットに存在する場合、ルーティングテーブルルールが、インターネットゲートウェイを使用してトラフィックを送信するように設定されていない。
  • インスタンスがプライベートサブネットに存在する場合、ルーティングテーブルルールが、NAT ゲートウェイまたは VPC エンドポイントを使用してトラフィックを送信するように設定されていない。
  • ルーティングテーブルルールがすべての発信接続でプロキシを使用するように設定されている場合、SSM Agent がプロキシを使用するように設定されていない。

SSM Agent には、必要な Systems Manager API 呼び出しを行うためのアクセス許可がない

SSM Agent は、サービスへの UpdateInstanceInformation API 呼び出しを行う権限がないため、Systems Manager で自身をオンラインとして登録できなかった。

SSM Agent との接続を維持して、SSM Agent が期待どおりに機能していることをサービスが認識できるようにするために、UpdateInstanceInformation API 呼び出しが必要となります。SSM Agent は、ヘルスチェック情報を提供するために、5 分ごとにクラウドで Systems Manager サービスを呼び出します。SSM Agent が正しい IAM アクセス許可を持っていない場合、SSM Agent のログに次のようなエラーメッセージが表示されます。

SSM Agent が不正な IAM アクセス許可を使用する場合:

AWS API を呼び出すときの ERROR [instanceID=i-XXXXX] [HealthCheck] エラー。エラーの詳細 - AccessDeniedException: ユーザー: arn:aws:sts::XXX:assumed-role/XXX /i-XXXXXX には実行するための権限がありません: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:XXXXXXX:instance/i-XXXXXX
ステータスコード: 400, リクエスト ID: XXXXXXXX-XXXX-XXXXXXX
INFO [instanceID=i-XXXX] [HealthCheck] エラー数を 1 ずつ増加

SSM Agent に IAM アクセス許可がない場合:

AWS API を呼び出すときの ERROR [instanceID=i-XXXXXXX] [HealthCheck] エラー。エラーの詳細 - NoCredentialProviders: チェーン内に有効なプロバイダーがありません。非推奨です。詳細なメッセージングについては、aws.Config.CredentialsChainVerboseErrors を参照してください
2018-05-08 10:58:39 INFO [instanceID=i-XXXXXXX] [HealthCheck] エラー数を 1 ずつ増加

インスタンスにアタッチされた IAM ロールに、インスタンスが Systems Manager のサービスコア機能を使用できるようにするために必要なアクセス許可が含まれていることを確認します。または、インスタンスプロファイルロールがまだアタッチされていない場合は、インスタンスプロファイルロールをアタッチし、AmazonSSMManagedInstanceCore アクセス許可を含めます。

Systems Manager に必要な IAM アクセス許可の詳細については、Systems Manager インスタンスプロファイルのポリシーについてを参照してください。

Systems Manager API 呼び出しスロットリング

SSM Agent を実行している多数のマネージドインスタンスが UpdateInstanceInformation API 呼び出しを同時に実行すると、API 呼び出しがスロットリングされることがあります。

インスタンスの UpdateInstanceInformation API 呼び出しがスロットリングされると、SSM Agent ログに次のようなエラーメッセージが表示されます。

INFO [HealthCheck] HealthCheck がエージェントの正常性をレポートしています。
AWS API を呼び出すときの ERROR [HealthCheck] エラー。エラーの詳細 - ThrottlingException: レートを超過しました
ステータスコード: 400, リクエスト ID: XXXXX-XXXXX-XXXX
INFO [HealthCheck] エラー数を 1 ずつ増加

ThrottlingException エラーを防ぐには、次のトラブルシューティング手順を試してください。

  • API 呼び出しの頻度を減らします。
  • API 呼び出しを行うときに、エラーの再試行とエクスポネンシャルバックオフを実装します。
  • API 呼び出しの間隔をずらし、すべてが同時に実行されないようにします。
  • UpdateInstanceInformation API 呼び出しのスロットリング制限の引き上げをリクエストします。

この記事はお役に立ちましたか?


請求に関するサポートまたは技術サポートが必要ですか?