如何解决 Systems Manager Agent 停滞在启动状态或无法启动的问题？

4 分钟阅读

我想解决 AWS Systems Manager Agent（SSM Agent）停滞在启动状态或无法启动的问题。

简短描述

托管实例是指配置为与 Systems Manager 配合使用的 Amazon EC2 实例。托管实例可以使用 Systems Manager 服务，例如 Run Command、补丁管理器和会话管理器。

确保您的 Amazon Elastic Compute Cloud（Amazon EC2）实例满足以下先决条件才能成为托管实例：

该实例已安装并运行了 SSM Agent。
该实例已连接到实例元数据服务。
该实例使用 SSM Agent 与 Systems Manager 端点相连接。
该实例附加了正确的 AWS Identity and Access Management（IAM）角色。

如果不满足这些先决条件，则 SSM Agent 不会启动。

对于 SSM Agent 版本 3.1.501.0 以及更高版本，您可以使用 ssm-cli 工具来确定实例是否满足这些要求。借助此工具，您可以诊断正在运行的 EC2 实例为什么未包含在 Systems Manager 的托管实例列表中。

如果您的实例未在 Systems Manager 控制台中显示为托管实例，请查看 SSM Agent 日志以进一步排除故障。

您可以在 /var/log/amazon/ssm 上找到 Linux 版 SSM Agent 日志。
您可以在 %PROGRAMDATA%\Amazon\SSM\Logs 上找到 Windows 版 SSM Agent 日志。

注意：如果实例未向 Systems Manager 报告，请尝试使用 RDP（Windows）或 SSH（Linux）登录以收集日志。如果您仍然无法登录，请停止该实例并分离根卷。然后，将根卷附加到与辅助卷位于同一可用区的另一个实例，以获取日志。

解决方法

**注意：**如果在运行 AWS 命令行界面（AWS CLI）命令时收到错误，请确保您使用的是最新的 AWS CLI 版本。

确保您已安装最新版本的 SSM Agent

最佳实践是使用最新版本的 SSM Agent。

对于 Linux，请参阅在 Linux 版 EC2 实例上手动安装 SSM Agent。

对于 Windows，请参阅在 Windows Server 版 EC2 实例上手动安装 SSM Agent。

检查至实例元数据服务的连接

**注意：**仅 EC2 实例需要此连接，而混合激活则不需要。

SSM Agent 必须使用 EC2 实例元数据才能正常工作。SSM Agent 可以使用实例元数据服务版本 1（IMDSv1）或实例元数据服务版本 2（IMDSv2）访问实例元数据。请确保实例能够访问实例元数据服务的 IPv4 地址： 169.254.169.254。

要验证至实例元数据服务的连接，请从 EC2 实例运行下列命令：

Linux：

telnet 169.254.169.254 80
or
curl -I http://169.254.169.254/latest/meta-data/

Windows：

curl http://169.254.169.254/latest/meta-data/  
or
Test-NetConnection 169.254.169.254  -port 80

如果实例无法访问元数据，请确保元数据已启用。

对于现有 EC2 实例，请执行以下操作来检查元数据是否已启用：

打开 Amazon EC2 控制台。
在导航窗格中，选择实例。
选择您的实例。
选择操作、实例设置、修改实例元数据选项。
在修改实例元数据选项对话框中，检查是否已启用实例元数据服务。

或者，使用 describe-instances 命令来验证实例元数据服务是否已启用：

aws ec2 describe-instances --query "Reservations[*].Instances[*].MetadataOptions" --instance-ids i-012345678910

输出结果如下所示：

[
  [
    {
      "State": "applied",
      "HttpTokens": "optional",
      "HttpPutResponseHopLimit": 1,
      "HttpEndpoint": "enabled",
      "HttpProtocolIpv6": "disabled",
      "InstanceMetadataTags": "disabled"
    }
  ]
]

前面输出中的 HttpEndpoint 字段指示元数据是否已启用。

如果元数据访问已关闭，请将其启用。

如果在实例中配置了代理，请确保该实例会绕过元数据 IP（169.254.169.254）。有关详细信息，请参阅下面的用户指南：

Linux：将 SSM Agent 配置为使用代理（Linux）

Windows：将 SSM Agent 配置为对 Windows Server 实例使用代理

对于 Windows，请查看通往元数据的特定路由（169.254.169.254）。

在 PowerShell 中，运行 route print 和 ipconfig /all 命令。然后，查看元数据输出：

    Network Address        Netmask             Gateway Address
    169.254.169.254        255.255.255.255     <Subnet Router Address>

确认输出中的 Gateway Address 字段与实例主网络接口的默认网关匹配。

如果路由不存在或 Gateway Address 字段不匹配，请执行下列操作：

确认实例上安装有最新版本的 EC2Config（Windows Server 2012R2 及更早版本）或 EC2Launch（Windows Server 2016 或更高版本）。
要将路由应用到实例，请重启 EC2Config 服务。
如果路由正确，但实例仍然无法检索元数据，请查看实例的 Windows 防火墙、第三方防火墙和防病毒配置。确认没有明确拒绝流向 169.254.169.254 的流量。

要手动重置元数据路由，请执行下列操作：

**注意：**这些配置的更改会立即填充。无需重启实例，更改亦可生效。

运行下列命令以从路由表中删除现有元数据路由：

route delete 169.254.169.123
route delete 169.254.169.249
route delete 169.254.169.250
route delete 169.254.169.251
route delete 169.254.169.252
route delete 169.254.169.253
route delete 169.254.169.254

运行以下命令：
```
ipconfig /all
```
请注意步骤 2 中的命令返回的默认网关 IP。

运行以下命令。将 DefaultGatewayIP 替换为您在步骤 3 中检索到的 IP 地址。

route -p add 169.254.169.123 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.249 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.250 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.251 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.252 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.253 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.254 MASK 255.255.255.255 DefaultGatewayIP

重启 SSM Agent。

检查与 Systems Manager 端点的连接

验证此连接的最佳方法因您的操作系统而异。有关按区域划分的 Systems Manager 端点列表，请参阅 AWS Systems Manager 端点和限额。

**注意：**在以下示例中，只有 AWS Systems Manager 会话管理器需要 ssmmessages 端点。

对于 EC2 Linux 实例，请运行 telnet 或 netcat 命令来验证与端口 443 上端点的连接。

Telnet

telnet ssm.RegionID.amazonaws.com 443
telnet ec2messages.RegionID.amazonaws.com 443
telnet ssmmessages.RegionID.amazonaws.com 443

请务必将 RegionID 替换为您的 AWS 区域 ID。

如果连接成功，那么您会收到类似于以下内容的输出：

root@111800186:~# telnet ssm.us-east-1.amazonaws.com 443
Trying 52.46.141.158...
Connected to ssm.us-east-1.amazonaws.com.
Escape character is '^]'.
To exit from telnet, hold down the Ctrl key and press the ] key. Enter quit, and then press Enter.

Netcat

nc -vz ssm.RegionID.amazonaws.com 443
nc -vz ec2messages.RegionID.amazonaws.com 443
nc -vz ssmmessages.RegionID.amazonaws.com 443

**注意：**Netcat 未预安装在 Amazon EC2 实例上。要手动安装 Netcat，请参阅 Nmap 网站上的 Ncat。

对于 EC2 Windows 实例，请运行以下 Windows PowerShell 命令来验证与端口 443 上端点的连接：

Test-NetConnection ssm.RegionID.amazonaws.com -port 443
Test-NetConnection ec2messages.RegionID.amazonaws.com -port 443
Test-NetConnection ssmmessages.RegionID.amazonaws.com -port 443

如果连接成功，那么您会收到类似于以下内容的输出：

PS C:\Users\ec2-user> Test-NetConnection ssm.us-east-1.amazonaws.com -port 443
ComputerName     : ssm.us-east-1.amazonaws.com
RemoteAddress    : 52.46.145.233
RemotePort       : 443
InterfaceAlias   : Ethernet
SourceAddress    : 10.35.218.225
TcpTestSucceeded : True

检查 SSM Agent 的 IAM 角色

SSM Agent 需要特定 IAM 权限才能进行 Systems Manager API 调用。您可以使用以下方法之一管理这些权限：

默认主机管理配置允许 Systems Manager 自动管理您的 Amazon EC2 实例。它允许在未使用实例配置文件的情况下管理实例。此配置可确保 Systems Manager 有权管理区域和账户中的所有实例。
您可以使用 IAM 实例配置文件在实例级别授予访问权限。实例配置文件是指在启动时将 IAM 角色信息传递给实例的容器。有关详细信息，请参阅备选配置。