如何使用 SSM Agent 日志排查托管实例中的 SSM Agent 问题?
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 需要 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 命令行界面(AWS CLI)中运行以下命令。请确保用您的实例 ID 替换 i-1234567898abcdef0:
**注意:**如果在运行 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 权限的更多信息,请参阅 Additional policy considerations for managed instances。
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"。
相关内容
- AWS 官方已更新 2 年前
- AWS 官方已更新 2 年前
- AWS 官方已更新 4 年前