如何使用 SSM 代理日志排查托管实例中的 SSM 代理问题?

上次更新日期:2021 年 6 月 8 日

AWS Systems Manager 代理(SSM 代理)无法成功运行,但我不知道如何使用 SSM 代理日志排查该问题。如何访问和解释 SSM 代理日志消息?

简短描述

SSM 代理在您托管的 Amazon Elastic Compute Cloud (Amazon EC2) 实例上运行,并处理来自 AWS Systems Manager 服务的请求。使用 SSM 代理必须满足以下条件:

  • SSM 代理必须连接到所需的服务终端节点。
  • SSM 代理需要 AWS Identity and Access Management (IAM) 权限才能调用 Systems Manager API 调用。

如果不满足这些条件中的任一条件,SSM 代理将无法成功运行。

要确定 SSM 代理失败的根本原因,请查看以下位置的 SSM 代理日志

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 代理配置自动更新,因为 SSM 代理会频繁更新新功能。

解决方法

在查看日志并确定 SSM 代理问题是否由缺少终端节点连接或缺少权限引起后,请按照以下故障排除步骤执行操作:

SSM 代理无法与所需的终端节点通信

SSM 代理无法访问元数据服务

SSM 代理无法从实例元数据服务中找到区域信息、IAM 角色和实例 ID,因为 SSM 代理无法访问元数据服务。

当 SSM 代理无法访问元数据服务终端节点时,您会在 SSM 代理日志中看到类似于以下内容的错误消息:

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 代理配置为使用代理。请务必将 SSM 代理配置为使用代理

在 Windows 实例上,当您使用自定义 AMI 启动实例时,错误配置的持久网络路由也可能导致该错误。您必须验证元数据服务 IP 的路由是否指向正确的默认网关。

SSM 代理无法访问 Systems Manager 服务终端节点

SSM 代理必须与端口 443 上的以下 Systems Manager 服务 API 调用建立出站连接。如果未建立连接,SSM 代理将失败。

  • SSM 终端节点:ssm.REGION.amazonaws.com
  • EC2 消息传递终端节点:ec2messages.REGION.amazonaws.com
  • SSM 消息传递终端节点:ssmmessages.REGION.amazonaws.com

注意:SSM 代理使用实例元数据服务检索到的区域信息来替换上述终端节点中的 REGION 值。

当 SSM 代理无法连接到 Systems Manager 终端节点时,您会在 SSM 代理日志中看到类似于以下内容的错误消息:

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 代理无法与端口 443 上的 Systems Manager API 终端节点连接的一些常见原因:

  • 实例出口安全组规则不允许端口 443 上的传出连接。
  • Virtual private cloud (VPC) 终端节点入口和出口安全组规则不允许与端口 443 上的 VPC 接口终端节点的传入和传出连接。
  • 当实例位于公共子网中时,路由表规则未配置为使用互联网网关引导流量。
  • 当实例位于私有子网中时,路由表规则未配置为使用 NAT 网关或 VPC 终端节点引导流量。
  • 如果路由表规则配置为对所有传出连接使用代理,则 SSM 代理不会配置为使用代理。

SSM 代理无权调用所需的 Systems Manager API 调用

SSM 代理无法在 Systems Manager 上将自身注册为联机,因为 SSM 代理无权对服务进行 UpdateInstanceInformation API 调用。

UpdateInstanceInformation API 调用需要维护与 SSM 代理的连接,以便服务知道 SSM 代理按预期运行。SSM 代理每五分钟调用一次云中的 Systems Manager 服务以提供运行状况检查信息。

如果 SSM 代理没有正确的 IAM 权限,您会在 SSM 代理日志中看到类似于以下内容的错误消息。

如果 SSM 代理使用了不正确的 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 代理没有任何 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 实例配置文件的策略

Systems Manager API 调用限制

如果运行 SSM 代理的大量托管实例进行并发 UpdateInstanceInformation API 调用,则 API 调用可能会受到限制。

如果实例的 UpdateInstanceInformation API 调用受到限制,您会在 SSM 代理日志中看到类似于以下内容的错误消息:

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 调用的节流限制。

这篇文章对您有帮助吗?


您是否需要账单或技术支持?