SSM Agent のログを参考に、マネージドインスタンス内の SSM Agent に関連する問題をトラブルシューティングする方法を教えてください。

簡単な説明

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

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

• SSM Agent は、必要なサービスエンドポイントに接続している必要があります。
• SSM Agent には、Systems Manager API オペレーションを呼び出すための AWS Identity and Access Management (IAM) アクセス許可が必要です。
• Amazon EC2 は IAM インスタンスプロファイルから有効な認証情報を取得する必要があります。または、デフォルトのホスト管理設定を設定した場合、Amazon EC2 は提供するデフォルトロールから認証情報を取得する必要があります。

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 のログを使用して問題のトラブルシューティングを行うには、お使いのオペレーティングシステム (OS) に対応する ssm-cli command コマンドを実行します。次に、出力に応じて次のトラブルシューティング手順を実行します。

SSM Agent がメタデータサービスに到達できない

Systems Manager が正しく機能するには、インスタンスメタデータが必要です。Systems Manager は、バージョン 1 またはバージョン 2 のインスタンスメタデータサービス (IMDSv1 と IMDSv2) を使用してインスタンスメタデータにアクセスできます。インスタンスは、インスタンスメタデータサービスの IPv4 アドレスである 169.254.169.254 にアクセスできる必要があります。

SSM Agent がメタデータサービスに到達できない場合、AWS リージョン、IAM ロール、またはインスタンス ID も取得できません。次の例のようなエラーメッセージは、SSM Agent がメタデータサービスに到達できないことを示しています。

"INFO- Failed to fetch instance ID.Data from vault is empty.RequestError: send request failed caused by: Get http://169.254.169.254/latest/meta-data/instance-id"

このエラーは、SSM Agent がプロキシを使用するように設定する前に、インスタンスからのアウトバウンドインターネット接続にプロキシを使用した場合に発生します。この問題を解決するには、プロキシを使用するように SSM Agent を設定します。

このエラーは、カスタム Amazon マシンイメージ (AMI) を使用して Windows インスタンスを正しくない静的ネットワークルートで起動した場合にも発生します。メタデータサービス IP のルートが正しいデフォルトゲートウェイを指していることを確認してください。詳細については、「Amazon EC2 Windows インスタンスで "Waiting for the metadata service" エラーが発生する場合のトラブルシューティング方法を教えてください」を参照してください。

インスタンスのメタデータが有効化されているかどうかを確認するには、次の AWS CLI コマンド describe-instances を実行します。

aws ec2 describe-instances --instance-ids example-id --query 'Reservations[*].Instances[*].MetadataOptions'

注: example-id を実際のインスタンス ID に置き換えてください。

次の出力例で、"HttpEndpoint": "enabled" は、インスタンスのメタデータが有効化されていないことを示しています。

“[ [{ "State": "applied", "HttpTokens": "optional", "HttpPutResponseHopLimit": 1, "HttpEndpoint": "enabled", "HttpProtocolIpv6": "disabled", "InstanceMetadataTags": "disabled" }] ]”

メタデータを有効化しなかった場合は、インスタンスのメタデータオプションを変更して有効にします。

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

SSM Agent がサービスエンドポイントに接続できない場合、SSM Agent は Systems Manager と通信できません。SSM Agent は、ポート 443 で SSM エンドポイント ssm.region.amazonaws.com へのアウトバウンド接続を行い、Systems Manager API オペレーションを実行する必要があります。AWS Systems Manager の機能である Session Manager または Run Command を使用する必要がある場合は、SSM Agent も ssmmessages.region.amazonaws.com エンドポイントに接続する必要があります。SSM Agent の Amazon Virtual Private Cloud (Amazon VPC) 設定要件の詳細については、「Systems Manager のために VPC エンドポイントを使用して EC2 インスタンスのセキュリティを強化する」を参照してください。

注: SSM Agent は、インスタンスメタデータサービスからリージョンを取得し、そのリージョンを使用してエンドポイント URL を作成します。

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

"ERROR [HealthCheck] error when calling AWS APIs. error details - RequestError: send request failed caused by: Post https://ssm.ap-southeast-2.amazonaws.com/: dial tcp [IP_ADDRESS]: i/o timeout"

このエラーを解決する方法については、「"RequestError: send request failed caused by:" という SSM Agent ログのエラーを 解決する方法を教えてください」を参照してください。

問題が解決しない場合は、以下の指示に従ってください。 使用している Amazon EC2 インスタンスが、Systems Manager でマネージドインスタンスとして表示されない原因を教えてください

SSM Agent に、必要な Systems Manager API コールを呼び出すためのアクセス許可がない

SSM Agent がサービスに対して UpdateInstanceInformation API コールを行うことを許可されていないため、SSM Agent を Systems Manager でオンラインとなるように登録できません。詳細については、「ssm:* 名前空間インスタンス関連の API オペレーション」を参照してください。

UpdateInstanceInformation API コールは SSM Agent との接続を維持して、SSM Agent が正しく機能していることをサービスが認識できるようにする必要があります。SSM Agent は、5 分ごとにクラウド内の Systems Manager サービスを呼び出してヘルスチェック情報を提供します。

SSM Agent が誤った IAM アクセス許可を使用している場合、次のメッセージ例のようなエラーが表示されます。

"ERROR [instanceID=i-12345] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::123:assumed-role/123 /i-123456 is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:1234567:instance/i-123456 status code: 400, request id: 12345678-1234-1234567 INFO [instanceID=i-1234] [HealthCheck] increasing error count by 1"

SSM Agent に IAM アクセス許可がない場合は、次のメッセージ例のようなエラーが表示されます。

"ERROR [instanceID=i-1234567] [HealthCheck] error when calling AWS APIs. error details - NoCredentialProviders: no valid providers in chain.Deprecated.For verbose messaging see aws.Config.CredentialsChainVerboseErrors 2018-05-08 10:58:39 INFO [instanceID=i-1234567] [HealthCheck] increasing error count by 1"

インスタンスにアタッチされている IAM ロールに AmazonSSMManagedInstanceCore AWS マネージドポリシーのアクセス許可が含まれていることを確認します。フィールドが空白の場合は、インスタンスプロファイルロールをアタッチし、AmazonSSMManagedInstanceCore アクセス許可を含めてください。

Systems Manager に必要な IAM アクセス許可の詳細については、「マネージドインスタンスのポリシーに関するその他の考慮事項」を参照してください。

Systems Manager API コールのスロットリング

複数のマネージドインスタンスが UpdateInstanceInformation API オペレーションを同時に呼び出すと、Systems Manager がそれらの呼び出しを制限することがあります。

次の例のようなエラーメッセージは、Systems Manager がインスタンスの UpdateInstanceInformation API オペレーションを制限したことを示しています。

"INFO [HealthCheck] HealthCheck reporting agent health.ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: Rate exceeded status code: 400, request id: 12345-12345-1234 INFO [HealthCheck] increasing error count by 1"

以下のトラブルシューティング手順を実行すると、"ThrottlingException" エラーを回避できます。

• API コールの頻度を減らします。
• HealthFrequencyMinutes パラメータをカスタマイズした場合は、パラメータをデフォルトの 5 分間隔に戻してください。
• API コールの間隔をずらして、すべてが同時に実行されないようにします。

前のトラブルシューティング手順を実行した後でも “ThrottlingException” エラーが表示される場合は、マネージドノードの使用クォータの引き上げをリクエストしてください。手順については、「AWS サービスクォータ」を参照してください。詳細については、「マネージドノードのサービスクォータ」を参照してください。

重要: サービスクォータを増やすと、アカウントに請求が発生します。詳細については、「AWS Systems Manager の料金」を参照してください。

Amazon EC2 は IAM インスタンスプロファイルからの有効な認証情報を引き継ぐことができない

Amazon EC2 が IAM ロールを引き受けられない場合は、SSM Agent のログに次の例のようなメッセージが複数表示されます。

"2023-01-25 09:56:19 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity"

"2023-01-25 09:56:19 INFO [CredentialRefresher] Sleeping for 1s before retrying retrieve credentials"

IMDSv1 を使用してインスタンスからメタデータを取得すると、次のエラー例を含むメッセージが表示されます。

"EC2 cannot assume the role example-instance-profile-name.Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc."

IMDSv2 を使用することがベストプラクティスです。ただし、IMDSv2 を使用する場合、次のコマンドは機能しません。

# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/example=instanceprofile-name

注: 上記のコマンドでは、example-instance-profile-name はインスタンスプロファイルの名前です。

インスタンスメタデータにアクセスする方法の詳細については、「EC2 インスタンスのインスタンスメタデータにアクセスする」を参照してください。

これらのエラーをトラブルシューティングするには、IAM ロールにアタッチされている信頼ポリシーを確認してください。このポリシーでは、IAM ロールを引き受けることが許可されているサービスとして Amazon EC2 を指定します。更新されたポリシーは、次の例のようになります。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": ["ec2.amazonaws.com"] }, "Action": ["sts:AssumeRole"] } ] }

信頼ポリシーを更新したら、自動的にスケジュールされた次回の認証情報の更新を待ちます。変更をすぐに実装するには、インスタンスプロファイルの関連付けを解除してから再関連付けするか、インスタンスを停止して再起動します。

信頼ポリシーをプログラムで更新するには、UpdateAssumeRolePolicy API を使用します。詳細については、「iam/security-credentials/[role-name] ドキュメントで "Code":"AssumeRoleUnauthorizedAccess" が表示される」を参照してください。