如何使用 SSM Agent 日志排查托管实例中的 SSM Agent 问题？

简短描述

注意： 如果您在运行 AWS 命令行界面 (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 需要 AWS Identity and Access Management (IAM) 权限才能调用 Systems Manager API 操作。
• 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 可以使用实例元数据服务（IMDSv1 和 IMDSv2）的版本 1 或版本 2 来访问实例元数据。您的实例必须能够访问 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"

当您在将 SSM Agent 配置为使用代理之前，使用代理进行实例的出站互联网连接时，就会出现此错误。要解决此问题，请将 SSM Agent 配置为使用代理。

当您使用自定义亚马逊机器映像 (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 无法连接服务端点，则 SSM Agent 无法与 Systems Manager 通信。SSM Agent 必须通过端口 443 与 SSM 端点 ssm.region.amazonaws.com 建立出站连接才能执行 Systems Manager API 操作。如果您必须使用 AWS Systems Manager 的会话管理器或 Run Command 功能，则 SSM Agent 还必须连接到 ssmmessages.region.amazonaws.com 端点。有关 SSM Agent 的 Amazon Virtual Private Cloud (Amazon VPC) 配置要求的更多信息，请参阅使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性。

注意： SSM Agent 从实例元数据服务中检索您的区域，并使用它来构建端点 URL。

当 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 调用，SSM Agent 无法在 Systems Manager 上将自身注册为联机。有关更多信息，请参阅 ssm:* namespace instance-related API operations（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 权限的更多信息，请参阅 Additional policy considerations for managed instances（托管实例的其他策略注意事项）。

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 服务配额。有关详细信息，请参阅 Service quotas for Managed nodes（托管节点的服务配额）。

重要事项： 当您增加服务配额时，您的账户会产生费用。有关详细信息，请参阅 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"。