部署SSM Agent on Linux

文档属性

文档属性	说明
难度	初级
预计时间	10-20 分钟
演示环境	Ubuntu 24.04 LTS / AWS EC2
最后验证	请参考 AWS 官方文档获取最新信息

任务目标

完成本指南后，你将能够：

• 确认或安装 SSM Agent
• 配置 EC2 实例以接受 Systems Manager 管理
• 在 Fleet Manager 中查看托管实例

前置条件

• 一台运行中的 EC2 实例（本文以 Ubuntu 24 为例）
• 具有 IAM 权限的 AWS 账户（能创建 IAM Role）
• 实例具备公网访问能力或配置了 VPC Endpoint

规划说明

在动手之前，理解以下关键点：

Ubuntu 24.04 是否需要手动安装？

不需要。AWS 官方 Ubuntu AMI（18.04 及以上版本）已预装 SSM Agent。本文档的重点是验证和配置，而非从零安装。仅当使用自定义 AMI 或 Agent 损坏时才需要手动安装。

为什么使用 IAM Role 而非 Default Host Management Configuration？

AWS 提供两种方式让实例接入 Systems Manager：

• IAM Instance Profile（本文方案）：为实例附加包含 AmazonSSMManagedInstanceCore 策略的 Role。优点是权限明确、可按需扩展。
• Default Host Management Configuration：账户级别的统一配置，自动管理所有实例。适合大规模部署，但要求 IMDSv2 和较新版本的 SSM Agent。

对于学习和小规模场景，IAM Instance Profile 更直观，便于理解权限模型。

网络连通性要求

SSM Agent 需要通过 HTTPS（端口 443）访问以下端点：

• ssm.<region>.amazonaws.com
• ssmmessages.<region>.amazonaws.com
• ec2messages.<region>.amazonaws.com

可通过公网（Internet Gateway/NAT Gateway）或 VPC Endpoint 实现。

1. 验证 SSM Agent 状态

SSH 连接到实例后，检查 Agent 是否已安装并运行：

sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service

预期输出应显示 active (running)。

如果服务未运行，启动它：

sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service

设置开机自启：

sudo systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service

Ubuntu 18.04 及以上版本使用 Snap 包管理 SSM Agent，服务名称较长。其他安装方式（如 deb 包）的服务名为 amazon-ssm-agent。

2. 创建 IAM Role

在 AWS Console 中操作：

1. 打开 IAM Console
2. 选择 角色 > 创建角色
3. 可信实体类型 选择 AWS 服务
4. 使用案例 选择 EC2，点击 下一步
5. 搜索并选择 AmazonSSMManagedInstanceCore（AWS 托管策略）
6. 点击 下一步，输入 角色 名称（如 SSMInstanceRole）
7. 点击 创建角色

如需使用 CloudWatch Agent，可同时附加 CloudWatchAgentServerPolicy 策略。

3. 附加 Role 到 EC2 实例

1. 打开 EC2 Console
2. 选择目标实例
3. 点击 操作 > 安全 > 修改 IAM 角色
4. 选择刚创建的 SSMInstanceRole
5. 点击 更新 IAM 角色

4. 重启SSM Agent

附加 IAM Role 后，必须重启 SSM Agent 使其获取新凭证：

sudo systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent.service

5. 验证托管实例

等待约几分钟后：

1. 打开 Systems Manager Console
2. 选择 队列管理器
   1. 第一次使用，可能会出现配置默认主机管理；
   2. 
   3. 
3. 确认实例出现在列表中，状态为 在线

也可通过 Session Manager 测试连接：

1. 在 队列管理器 中选择实例
2. 点击 节点操作 > 连接 > 开启终端会话。还可以：
   1. 重置密码
   2. 运行Shell命令
3. 成功打开终端即表示配置完成

架构流程

%%{init: {"elk": true}}%%
flowchart LR
    subgraph EC2["EC2 Instance"]
        Agent["SSM Agent"]
    end
    
    subgraph AWS["AWS Services"]
        IAM["IAM Role"]
        SSM["Systems Manager"]
        FM["Fleet Manager"]
    end
    
    IAM -.->|临时凭证| Agent
    Agent -->|HTTPS 443| SSM
    SSM --> FM

手动安装（仅在必要时）

如果实例未预装 SSM Agent（如自定义 AMI），使用以下命令安装：

sudo snap install amazon-ssm-agent --classic
sudo systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service
sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service

其他安装方式（deb 包、其他操作系统）请参考 AWS 官方安装文档。

常见问题

实例未出现在 队列管理器 中

按以下顺序排查：

检查项	排查方法
Agent 是否运行	sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service
IAM Role 是否附加	EC2 Console 检查实例的 IAM role 字段
网络是否连通	检查安全组出站规则是否允许 HTTPS 443
端点是否可达	curl -s https://ssm.<region>.amazonaws.com

查看 Agent 日志获取详细错误：

sudo cat /var/log/amazon/ssm/amazon-ssm-agent.log

IMDSv2 环境下验证 IAM Role

TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/

返回 Role 名称即表示 Role 已正确附加。

Session Manager 连接失败

除基础的 ssm 端点外，Session Manager 还需访问 ssmmessages 端点。确保网络配置允许访问：

• ssmmessages.<region>.amazonaws.com

扩展阅读

• SSM Agent 在 Ubuntu 上的安装
• 配置实例权限
• 使用 VPC Endpoint 提升安全性
• Default Host Management Configuration
• 托管实例故障排查

---

架构师建议配置

场景	推荐方案
单实例/学习环境	IAM Instance Profile + 公网访问
生产环境（小规模）	IAM Instance Profile + VPC Endpoint
生产环境（大规模）	Default Host Management Configuration + VPC Endpoint
私有子网无公网	必须配置 VPC Endpoint（ssm, ssmmessages, ec2messages）

核心原则：SSM Agent 本身通常已预装，重点是确保 IAM 权限和网络连通性。