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

簡短描述

SSM Agent 在您受管 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體上執行，並處理來自 AWS Systems Manager 服務的請求。SSM Agent 要求符合下列條件：

• SSM Agent 必須連接至所需的服務端點。
• SSM Agent 必須有 AWS Identity and Access Management (IAM) 許可，才能呼叫 Systems Manager API。
• 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 Command Line Interface (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 Agent 之前，使用其來進行執行個體的輸出網際網路連線時，通常會發生此錯誤。若要解決此問題，請將 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 [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 Agent 正在如預期運作。SSM Agent 每五分鐘呼叫一次雲端中的 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
status code: 400, request 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: Rate exceeded
status code: 400, request 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

如果您從 EC2 執行個體使用 IMDSv1 擷取中繼資料，您也會看到類似下列範例的錯誤：

# 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 角色的信任政策。在政策中，您必須將 Amazon EC2 指定為允許擔任 IAM 角色的服務。透過 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"。