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

所要時間4分

AWS Systems Manager 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 と 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 の自動更新を設定することがベストプラクティスです。

解決策

まず、ログを確認して、問題の原因がエンドポイント接続がないこと、アクセス許可がないこと、または認証情報が不足していることにあるかどうかを確認します。その後に、問題に関連するトラブルシューティングの手順に従います。

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 Agent をプロキシに対して設定せずに、インスタンスからのアウトバウンドインターネット接続にプロキシを使用していることです。SSM Agent がプロキシを使用するように設定してください。

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

インスタンスのメタデータが有効になっているかどうかを確認するには、AWS コマンドラインインターフェイス (AWS CLI) で次のコマンドを実行します。i-1234567898abcdef0 を確実に自分のインスタンス ID に置き換えます。

注: AWS CLI コマンドの実行中にエラーが発生した場合は、使用している AWS CLI が最新バージョンであることを確認してください。

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

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

[
  [{
    "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
EC2 メッセージングエンドポイント: ec2messages.REGION.amazonaws.com
SSM メッセージングエンドポイント: ssmmessages.REGION.amazonaws.com

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

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 172.31.24.65:443: i/o timeout」

「DEBUG [MessagingDeliveryService] RequestError: send request failed caused by: Post https://ec2messages.ap-southeast-2.amazonaws.com/: net/http: request cancelled while waiting for connection (Client.Timeout exceeded while awaiting headers)」

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 reporting agent health.
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 identity
2023-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

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 はインスタンスプロファイルの名前です。

このエラーをトラブルシューティングするには、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" が表示される」を参照してください。

トピック

管理とガバナンス

タグ

AWS Systems Manager

言語

日本語

AWS公式更新しました 1年前

コメントはありません