如何使用 SSM Agent 日誌，疑難排解受管執行個體中的 SSM Agent 問題？

簡短說明

注意： 如果您在執行 AWS Command Line Interface (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 命令。接著，請根據輸出完成以下疑難排解步驟。

SSM Agent 無法連線至中繼資料服務

Systems Manager 仰賴執行個體中繼資料才能正常運作。Systems Manager 可以使用執行個體中繼資料服務第 1 版或第 2 版 (IMDSv1 和 IMDSv2) 存取執行個體中繼資料。您的執行個體必須能夠存取 169.254.169.254，這是執行個體中繼資料服務的 IPv4 位址。

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」

如果您先使用 Proxy 處理執行個體的傳出網際網路連線，之後才將 SSM Agent 設定為使用 Proxy，便會發生此錯誤。若要解決此問題，請將 SSM Agent 設定為使用 Proxy。

如果您使用自訂 Amazon Machine Image (AMI) 啟動靜態網路路由設定不正確的 Windows 執行個體，也會發生此錯誤。確認中繼資料服務 IP 的路由指向正確的預設閘道。如需更多資訊，請參閱如何疑難排解 Amazon EC2 Windows 執行個體上的「Waiting for the metadata service」錯誤？

若要確認您的執行個體是否已啟用中繼資料，請執行以下 describe-instances AWS CLI 命令：

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 無法連線至服務端點，便無法與 Systems Manager 通訊。SSM Agent 必須連線至 SSM 端點 ssm.region.amazonaws.com 的連接埠 443，建立傳出連線，才能執行 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 會從執行個體中繼資料服務擷取區域，並用於建立端點網址。

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 日誌錯誤？

如果問題仍然存在，請依照以下說明操作： 為什麼 Systems Manager 未將我的 Amazon EC2 執行個體顯示為受管執行個體？

SSM Agent 沒有呼叫所需 Systems Manager API 的權限

SSM Agent 未獲授權對服務進行 UpdateInstanceInformation API 呼叫，因此無法在 Systems Manager 中將自己註冊為線上狀態。如需更多資訊，請參閱 ssm:* 命名空間中與執行個體相關的 API 操作。

UpdateInstanceInformation API 呼叫必須與 SSM Agent 保持連線，服務才能確認 SSM Agent 運作正常。SSM Agent 每五分鐘呼叫一次雲端中的 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 參數，請將該參數還原為預設的五分鐘間隔。
• 錯開 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 角色的信任政策。在政策中，將 Amazon EC2 指定為可擔任 IAM 角色的服務。更新後的政策應與以下範例類似：

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

更新信任政策後，請等候下一次排程的自動憑證重新整理。若要立即套用變更，請取消執行個體設定檔的關聯後再重新建立關聯，或停止再重新啟動執行個體。

若要以程式設計方式更新信任政策，請使用 UpdateAssumeRolePolicy API。如需相關指示，請參閱 iam/security-credentials/[role-name] 文件指出 "Code":"AssumeRoleUnauthorizedAccess"。