无法通过SSM连接EC2实例：SSM Agent未在线，求故障排查

• 检查VPC端点配置与网络连通性
  若使用VPC端点，需确保以下三类端点均已创建并关联到实例所在的VPC和子网：

  • com.amazonaws.<区域>.ssm（SSM核心服务端点）
  • com.amazonaws.<区域>.ec2messages（SSM Agent接收指令、上报状态的端点）
  • com.amazonaws.<区域>.ssmmessages（Session Manager会话数据传输端点）
    同时确认实例安全组允许出站HTTPS（443）流量到这些端点；未使用VPC端点的场景，需允许实例访问SSM服务的公网HTTPS地址。

• 验证IAM角色的信任关系与权限限制
  确认实例绑定的IAM角色信任策略包含EC2服务主体，示例策略如下：

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "ec2.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }
  

  此外需排查是否存在IAM权限边界或组织SCP（服务控制策略），限制了角色的SSM相关权限。

• 检查SSM Agent运行状态与日志
  若能通过SSH等方式登录实例，执行以下操作：

  • 查看Agent运行状态：
    Debian/Amazon Linux：sudo systemctl status amazon-ssm-agent
  • 若Agent未运行，启动并设置开机自启：

    sudo systemctl start amazon-ssm-agent
    sudo systemctl enable amazon-ssm-agent
    

  • 查看Agent日志定位错误：

    sudo tail -f /var/log/amazon/ssm/amazon-ssm-agent.log
    

    日志中常出现的连接超时、凭证获取失败等信息，可直接指向问题根源。

• 确认SSM Agent版本兼容性
  旧版本Agent可能存在兼容性问题，执行命令查看版本：amazon-ssm-agent -version
  版本较旧时手动更新：

  • Debian：

    wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb
    sudo dpkg -i amazon-ssm-agent.deb
    

  • Amazon Linux：sudo yum update amazon-ssm-agent -y

• 检查EC2实例元数据服务（IMDS）访问
  SSM Agent依赖IMDS获取IAM角色凭证，执行命令验证访问：

  curl http://169.254.169.254/latest/meta-data/iam/security-credentials/<你的IAM角色名称>
  

  若能返回有效凭证则IMDS正常；若无法访问，需确认实例未禁用IMDS，且安全组/路由表未限制对169.254.169.254的本地访问。

内容的提问来源于stack exchange，提问作者Jean François Manatane