如何使用 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 設定自動更新。

解決方法

首先，檢閱日誌，並確定問題是否由於遺失端點連線、遺失許可或遺失憑證所造成。然後，執行問題的相關疑難排解步驟。

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 Command Line Interface (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 無法在 Systems Manager 上將自身註冊為線上狀態，因為 SSM Agent 未獲授權對服務進行 UpdateInstanceInformation API 呼叫。

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 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 角色的信任政策。在政策中，您必須將 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"。

---