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) アクセス許可が必要です。
• Amazon EC2 は 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 の自動更新を設定することがベストプラクティスです。

解決策

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

SSM Agent のログを参考に問題をトラブルシューティングするには、ssm-cli コマンドを実行します。次に、問題に応じて、次のトラブルシューティング手順を実行します。

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

ユースケースに基づいて、次のタスクを実行します。

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

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

Windows インスタンスでは、正しく設定されていない永続的なネットワーク経路が原因で、カスタム AMI を使用してインスタンスを起動するときにこのエラーが発生することもあります。メタデータサービス IP の経路が正しいデフォルトゲートウェイを指していることを確認する必要があります。詳細については、「Amazon EC2 Windows インスタンスで、"Waiting for the metadata service" というエラーが生成される理由を教えてください」を参照してください。

インスタンスでメタデータがアクティブ化されているかどうかを確認するには、AWS CLI で次のコマンドを実行します。

aws ec2 describe-instances --instance-ids i-1234567898abcdef0 --query 'Reservations[*].Instances[*].MetadataOptions'

注: i-1234567898abcdef0 は、お使いのインスタンス ID に置き換えます。

次の例のような出力が表示されます。

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

この出力では、"HttpEndpoint": "enabled" はインスタンスのメタデータがアクティブ化されていることを示しています。

メタデータがアクティブ化されていない場合は、aws ec2 modify-instance-metadata-options コマンドを実行するとメタデータを有効にできます。詳細については、「既存インスタンスのインスタンスメタデータオプションを変更する」を参照してください。

SSM Agent が Systems Manager サービスエンドポイントにアクセスできない場合

SSM Agent がサービスエンドポイントに接続できない場合、SSM Agent は動作しません。SSM Agent は、ポート 443 での Systems Manager サービス API コールの後、SSM エンドポイント ssm.REGION.amazonaws.com とのアウトバウンド接続を行う必要があります。

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

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

"ERROR AWS API の呼び出し時に [HealthCheck] エラーが発生しました。エラーの詳細 - RequestError: リクエストの送信が次の理由で失敗しました: Post https://ssm.ap-southeast-2.amazonaws.com/: dial tcp 172.31.24.65:443: i/o timeout" "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 コールを行うことを許可されていないため、SSM Agent を Systems Manager でオンラインとなるように登録できません。

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

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

「ERROR [instanceID=i-XXXXX] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::XXX:assumed-role/XXX /i-XXXXXX is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:XXXXXXX:instance/i-XXXXXX
ステータスコード: 400、リクエストID: XXXXXXXX-XXXX-XXXXXXX
INFO [instanceID=i-XXXX] [HealthCheck] increasing error count by 1」

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

「ERROR [instanceID=i-XXXXXXX] [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-XXXXXXX] [HealthCheck] increasing error count by 1」

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

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

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

SSM Agent を実行する大量のマネージドインスタンスが UpdateInstanceInformation API コールを同時に実行すると、それらのコールにスロットリングが発生する場合があります。

インスタンスの UpdateInstanceInformation API コールがスロットリングされている場合、SSM Agent のログに次のようなエラーメッセージが表示されます。

"INFO [HealthCheck] HealthCheck がエージェントの正常性を報告しています。
ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: レートを超過しました
ステータスコード: 400、リクエストID: XXXXX-XXXXX-XXXX
INFO [HealthCheck] increasing error count by 1」

以下のトラブルシューティング手順を使用すると、ThrottlingException エラーを防止できます。

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

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 identity2023-01-25 09:56:19 INFO [CredentialRefresher] Sleeping for 1s before retrying retrieve credentials
2023-01-25 09:56:20 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:20 INFO [CredentialRefresher] Sleeping for 2s before retrying retrieve credentials
2023-01-25 09:56:22 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:22 INFO [CredentialRefresher] Sleeping for 4s before retrying retrieve credentials
2023-01-25 09:56:26 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:26 INFO [CredentialRefresher] Sleeping for 9s before retrying retrieve credentials
2023-01-25 09:56:35 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:35 INFO [CredentialRefresher] Sleeping for 17s before retrying retrieve credentials
2023-01-25 09:56:52 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:52 INFO [CredentialRefresher] Sleeping for 37s before retrying retrieve credentials

IMDSv1 を使用して EC2 インスタンスからメタデータを取得している場合、次の例のようなエラーも表示されます。

# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/profile-name{
  "Code" : "AssumeRoleUnauthorizedAccess",
  "Message" : "EC2 cannot assume the role profile-name. Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc.",
  "LastUpdated" : "2023-01-25T09:57:56Z"
}

注: 上記の例では、profile-name はインスタンスプロファイルの名前です。IMDSv2 を使用している場合、上記のコマンドは機能しません。メタデータの取得に関する詳細については、インスタンスメタデータの取得に関する Linux および Windows 用のページを参照してください。

このエラーをトラブルシューティングするには、IAM ロールにアタッチされている信頼ポリシーを確認します。このポリシーでは、IAM ロールを引き継ぐことが許可されているサービスとして Amazon EC2 を指定する必要があります。UpdateAssumeRolePolicy API を使用して IAM ポリシーを更新し、次の例のように表示されるようにします。

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

詳細については、「iam/security-credentials/[role-name] ドキュメントで "Code":"AssumeRoleUnauthorizedAccess" が表示される」を参照してください。