SSM Agent 手动部署教程
AWS Systems Manager Agent (SSM Agent) 是一款可以在EC2实例上安装和配置的Amazon软件，它使Systems Manager能够更新、管理和配置这些实例。SSM Agent处理来自Systems Manager服务的请求，然后按照文档中的指定运行这些请求。
SSM Agent的主要功能
Section titled “SSM Agent的主要功能”- 远程命令执行 (Run Command)
- 会话管理 (Session Manager)
- 补丁管理 (Patch Manager)
- 状态管理 (State Manager)
- 参数存储访问 (Parameter Store)
在开始安装SSM Agent之前，请确保满足以下条件：
- 已创建EC2实例（Ubuntu 24.04 或 Rocky Linux 10）
- 实例可以访问外网（通过Internet Gateway或NAT Gateway）
- 实例运行在支持的AWS区域
- 具有SSH访问实例的权限
- 具有AWS管理控制台的访问权限
官方安装包地址
Section titled “官方安装包地址”AWS为不同的操作系统和架构提供了SSM Agent安装包。你可以从以下官方文档获取最新的安装包地址：
Ubuntu系统：
Rocky Linux系统：
所有Linux系统通用文档：
IAM角色配置
Section titled “IAM角色配置”在安装SSM Agent之前，必须先配置IAM角色和实例配置文件，使EC2实例具有与Systems Manager通信的权限。
步骤1：创建IAM角色
Section titled “步骤1：创建IAM角色”- 登录AWS管理控制台
- 导航至IAM服务：https://console.aws.amazon.com/iam/
- 在左侧导航栏中选择 Roles
- 点击 Create role 按钮
步骤2：配置信任关系
Section titled “步骤2：配置信任关系”- 在 Select trusted entity 页面：
- 选择 AWS service
- 在 Use case 部分选择 EC2
- 点击 Next
步骤3：附加权限策略
Section titled “步骤3：附加权限策略”- 在 Add permissions 页面的搜索框中输入：
AmazonSSMManagedInstanceCore - 勾选 AmazonSSMManagedInstanceCore 策略（这是AWS托管策略）
- 点击 Next
AmazonSSMManagedInstanceCore策略说明：
此策略包含SSM Agent核心功能所需的最小权限，包括：
- 与Systems Manager服务通信
- 发送实例状态信息
- 执行远程命令
- 建立Session Manager会话
步骤4：命名和创建角色
Section titled “步骤4：命名和创建角色”- 在 Role name 字段输入角色名称，例如：
EC2-SSM-Role - （可选）添加描述：
IAM role for EC2 instances to communicate with Systems Manager - （可选）添加标签
- 点击 Create role
步骤5：将IAM角色附加到EC2实例
Section titled “步骤5：将IAM角色附加到EC2实例”对于新实例：
- 在启动EC2实例时，在 Configure instance details 页面
- 在 IAM role 下拉菜单中选择刚创建的角色
EC2-SSM-Role
对于现有实例：
- 导航至EC2控制台：https://console.aws.amazon.com/ec2/
- 选择目标实例
- 点击 Actions > Security > Modify IAM role
- 从下拉列表中选择
EC2-SSM-Role - 点击 Update IAM role
重要提示： 如果在实例运行时附加IAM角色，可能需要等待几分钟或重启SSM Agent才能生效。
Ubuntu 24.04 部署SSM Agent
Section titled “Ubuntu 24.04 部署SSM Agent”Ubuntu 24.04系统使用Snap包管理器来安装SSM Agent。
步骤1：连接到实例
Section titled “步骤1：连接到实例”使用SSH连接到Ubuntu实例：
ssh -i /path/to/your-key.pem ubuntu@your-instance-public-ip步骤2：更新系统包
Section titled “步骤2：更新系统包”sudo apt update步骤3：安装SSM Agent
Section titled “步骤3：安装SSM Agent”Ubuntu 24.04使用Snap包来安装SSM Agent：
sudo snap install amazon-ssm-agent --classic注意： 大多数Ubuntu AWS AMI已预装SSM Agent。如果已安装，可以跳过此步骤。
步骤4：启动SSM Agent
Section titled “步骤4：启动SSM Agent”sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service步骤5：启用开机自启动
Section titled “步骤5：启用开机自启动”sudo systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service步骤6：检查SSM Agent状态
Section titled “步骤6：检查SSM Agent状态”sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service预期输出应显示服务状态为 active (running)：
● snap.amazon-ssm-agent.amazon-ssm-agent.service - Service for snap application amazon-ssm-agent.amazon-ssm-agent Loaded: loaded (/etc/systemd/system/snap.amazon-ssm-agent.amazon-ssm-agent.service; enabled; preset: enabled) Active: active (running) since Thu 2024-11-27 10:30:00 UTC; 5min ago Main PID: 1234 (amazon-ssm-agen) Tasks: 15 (limit: 1234) Memory: 50.0M CPU: 2s CGroup: /system.slice/snap.amazon-ssm-agent.amazon-ssm-agent.service └─1234 /snap/amazon-ssm-agent/current/amazon-ssm-agent步骤7：检查SSM Agent版本
Section titled “步骤7：检查SSM Agent版本”sudo snap list amazon-ssm-agent使用Snap管理SSM Agent的常用命令
Section titled “使用Snap管理SSM Agent的常用命令”停止服务：
sudo systemctl stop snap.amazon-ssm-agent.amazon-ssm-agent.service重启服务：
sudo systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent.service更新到最新版本：
sudo snap refresh amazon-ssm-agent切换到候选通道（获取最新功能）：
sudo snap switch --channel=candidate amazon-ssm-agentsudo snap refresh amazon-ssm-agentRocky Linux 10 部署SSM Agent
Section titled “Rocky Linux 10 部署SSM Agent”Rocky Linux使用DNF包管理器来安装SSM Agent的RPM包。
步骤1：连接到实例
Section titled “步骤1：连接到实例”使用SSH连接到Rocky Linux实例：
ssh -i /path/to/your-key.pem rocky@your-instance-public-ip步骤2：确认Python已安装
Section titled “步骤2：确认Python已安装”SSM Agent需要Python 2或Python 3才能正常工作：
python3 --version如果未安装Python 3，运行：
sudo dnf install python3 -y步骤3：下载并安装SSM Agent
Section titled “步骤3：下载并安装SSM Agent”对于x86_64架构（AMD64）：
sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm对于ARM64架构（Graviton）：
sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm注意： 虽然URL包含 ec2-downloads-windows 目录，但这是Rocky Linux的正确全球安装包地址。
使用区域特定的安装包（可选）
Section titled “使用区域特定的安装包（可选）”如果需要从特定AWS区域下载以提高速度，可以使用区域特定的URL。
格式：
sudo dnf install -y https://s3.REGION.amazonaws.com/amazon-ssm-REGION/latest/linux_amd64/amazon-ssm-agent.rpm示例（us-east-2区域）：
sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm步骤4：启动SSM Agent
Section titled “步骤4：启动SSM Agent”sudo systemctl start amazon-ssm-agent步骤5：启用开机自启动
Section titled “步骤5：启用开机自启动”sudo systemctl enable amazon-ssm-agent步骤6：检查SSM Agent状态
Section titled “步骤6：检查SSM Agent状态”sudo systemctl status amazon-ssm-agent预期输出应显示服务状态为 active (running)：
● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; preset: disabled) Active: active (running) since Thu 2024-11-27 10:30:00 UTC; 5min ago Main PID: 2345 (amazon-ssm-agen) Tasks: 18 (limit: 4096) Memory: 55.0M CPU: 1.5s CGroup: /system.slice/amazon-ssm-agent.service └─2345 /usr/bin/amazon-ssm-agent步骤7：检查SSM Agent版本
Section titled “步骤7：检查SSM Agent版本”sudo yum info amazon-ssm-agent或者：
rpm -qa | grep amazon-ssm-agent管理SSM Agent的常用命令
Section titled “管理SSM Agent的常用命令”停止服务：
sudo systemctl stop amazon-ssm-agent重启服务：
sudo systemctl restart amazon-ssm-agent查看日志：
sudo tail -f /var/log/amazon/ssm/amazon-ssm-agent.log手动更新SSM Agent：
sudo dnf update -y amazon-ssm-agent完成SSM Agent的安装后，需要验证实例是否已成功注册到Systems Manager并可以正常管理。
测试1：检查实例是否出现在队列管理器中
Section titled “测试1：检查实例是否出现在队列管理器中”- 登录AWS管理控制台
- 导航至Systems Manager：https://console.aws.amazon.com/systems-manager/
- 在左侧导航栏中，选择 Fleet Manager(队列管理器)（在 Node Management 下）
- 等待5-10分钟让实例注册
- 你的实例应该出现在托管实例列表中
预期结果： 你应该能看到实例ID、平台类型、IP地址和 Online 状态。
测试2：验证SSM Agent注册状态
Section titled “测试2：验证SSM Agent注册状态”使用AWS CLI验证实例是否已成功注册：
aws ssm describe-instance-information --output table预期输出示例：
--------------------------------------------------------------| DescribeInstanceInformation |+------------------------------------------------------------+|| InstanceInformationList |||+------------------------+----------------------------------+||| InstanceId | i-0123456789abcdef0 |||| PingStatus | Online |||| PlatformName | Ubuntu |||| PlatformVersion | 24.04 |||| PlatformType | Linux |||| AgentVersion | 3.2.2086.0 |||| IsLatestVersion | True |||+------------------------+----------------------------------+|测试3：使用ssm-cli进行诊断
Section titled “测试3：使用ssm-cli进行诊断”SSM Agent 3.1.501.0及更高版本包含内置的诊断工具。
Ubuntu系统：
sudo /snap/amazon-ssm-agent/current/ssm-cli get-diagnostics --output tableRocky Linux系统：
sudo /usr/bin/ssm-cli get-diagnostics --output table预期输出应显示所有检查项都为 Success：
┌───────────────────────────────────┬─────────┬──────────────────────────────────────┐│ Check │ Status │ Note │├───────────────────────────────────┼─────────┼──────────────────────────────────────┤│ EC2 IMDS │ Success │ IMDS is accessible and has instance ││ │ │ id i-xxx in Region us-east-1 │├───────────────────────────────────┼─────────┼──────────────────────────────────────┤│ Hybrid instance registration │ Skipped │ Instance does not have hybrid ││ │ │ registration │├───────────────────────────────────┼─────────┼──────────────────────────────────────┤│ Connectivity to ssm endpoint │ Success │ ssm.us-east-1.amazonaws.com is ││ │ │ reachable │├───────────────────────────────────┼─────────┼──────────────────────────────────────┤│ Connectivity to ec2messages │ Success │ ec2messages.us-east-1.amazonaws.com ││ endpoint │ │ is reachable │├───────────────────────────────────┼─────────┼──────────────────────────────────────┤│ Connectivity to ssmmessages │ Success │ ssmmessages.us-east-1.amazonaws.com ││ endpoint │ │ is reachable │└───────────────────────────────────┴─────────┴──────────────────────────────────────┘测试4：通过Session Manager连接实例
Section titled “测试4：通过Session Manager连接实例”- 在Systems Manager控制台中，选择 Session Manager
- 点击 Start session
- 选择你的实例
- 点击 Start session
- 应该会打开一个新的浏览器标签页，显示一个交互式shell
预期结果： 你应该能够通过浏览器访问实例的shell，无需SSH密钥。
测试5：使用Run Command执行命令
Section titled “测试5：使用Run Command执行命令”测试通过Run Command在实例上执行远程命令。
使用AWS CLI：
Ubuntu示例：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-RunShellScript" \ --parameters 'commands=["echo Hello from SSM Agent", "uname -a", "df -h"]' \ --output textRocky Linux示例：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-RunShellScript" \ --parameters 'commands=["echo Hello from SSM Agent", "cat /etc/os-release", "free -h"]' \ --output text命令将返回一个 CommandId。使用以下命令查看执行结果：
aws ssm list-command-invocations \ --command-id "COMMAND-ID-FROM-ABOVE" \ --details预期结果： 命令应成功执行，输出包含命令的执行结果。
测试6：安装Nginx并验证
Section titled “测试6：安装Nginx并验证”使用Run Command在实例上安装Nginx，测试SSM Agent执行复杂任务的能力。
Ubuntu系统安装Nginx：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-RunShellScript" \ --parameters 'commands=["sudo apt update -y", "sudo apt install nginx -y", "sudo systemctl start nginx", "sudo systemctl enable nginx", "sudo systemctl status nginx", "curl -I http://localhost"]' \ --comment "Install and start Nginx on Ubuntu" \ --output textRocky Linux系统安装Nginx：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-RunShellScript" \ --parameters 'commands=["sudo dnf install nginx -y", "sudo systemctl start nginx", "sudo systemctl enable nginx", "sudo systemctl status nginx", "curl -I http://localhost"]' \ --comment "Install and start Nginx on Rocky Linux" \ --output text验证Nginx安装：
- 记录返回的
CommandId - 查看命令执行详情：
aws ssm get-command-invocation \ --command-id "YOUR-COMMAND-ID" \ --instance-id "i-0123456789abcdef0"- 在浏览器中访问实例的公网IP地址，应该看到Nginx的欢迎页面
预期结果：
- 命令执行状态为
Success - Nginx服务运行正常
- 可以通过HTTP访问Nginx欢迎页面
如果以上所有测试都通过，说明SSM Agent已正确安装和配置，可以：
- 实例已成功注册到Systems Manager
- IAM权限配置正确
- 网络连接正常
- 可以远程管理和执行命令
如果SSM Agent安装后无法正常工作，以下是常见问题及解决方案。
问题1：实例未出现在Fleet Manager中
Section titled “问题1：实例未出现在Fleet Manager中”可能原因和解决方案：
原因1：SSM Agent未运行
检查SSM Agent状态：
Ubuntu:
sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.serviceRocky Linux:
sudo systemctl status amazon-ssm-agent如果未运行，启动服务：
Ubuntu:
sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.serviceRocky Linux:
sudo systemctl start amazon-ssm-agent原因2：IAM实例配置文件缺失或权限不足
验证实例是否附加了IAM角色：
aws ec2 describe-instances \ --instance-ids i-0123456789abcdef0 \ --query 'Reservations[0].Instances[0].IamInstanceProfile'如果输出为空，说明未附加IAM角色。参考前面的IAM角色配置部分附加角色。
验证IAM角色是否包含 AmazonSSMManagedInstanceCore 策略：
aws iam list-attached-role-policies --role-name EC2-SSM-Role原因3：网络连接问题
SSM Agent需要能够连接到以下端点：
ssm.region.amazonaws.comec2messages.region.amazonaws.comssmmessages.region.amazonaws.com
验证网络连接：
curl -I https://ssm.us-east-1.amazonaws.comcurl -I https://ec2messages.us-east-1.amazonaws.comcurl -I https://ssmmessages.us-east-1.amazonaws.com如果连接失败，检查：
- 实例是否有公网IP或位于有NAT Gateway的私有子网
- 安全组是否允许出站HTTPS（443端口）流量
- NACL是否阻止流量
原因4：实例元数据服务（IMDS）不可用
验证IMDS可访问：
curl http://169.254.169.254/latest/meta-data/instance-id如果失败，启用IMDS：
aws ec2 modify-instance-metadata-options \ --instance-id i-0123456789abcdef0 \ --http-tokens optional \ --http-endpoint enabled原因5：等待时间不足
SSM Agent注册可能需要5-10分钟。等待更长时间后再检查。
如果附加IAM角色到正在运行的实例，重启SSM Agent：
Ubuntu:
sudo systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent.serviceRocky Linux:
sudo systemctl restart amazon-ssm-agent问题2：SSM Agent状态显示”Connection Lost”
Section titled “问题2：SSM Agent状态显示”Connection Lost””解决方案：
- 检查SSM Agent日志文件
Ubuntu:
sudo journalctl -u snap.amazon-ssm-agent.amazon-ssm-agent.service -fRocky Linux:
sudo tail -f /var/log/amazon/ssm/amazon-ssm-agent.logsudo tail -f /var/log/amazon/ssm/errors.log- 查找错误信息，常见错误：
错误示例1： RegistrationFailed: Failed to register the instance
- 检查IAM角色权限
- 验证实例元数据服务是否可用
错误示例2： Unable to connect to Systems Manager endpoint
- 检查网络连接
- 验证安全组和NACL规则
- 重启SSM Agent并观察日志
问题3：Session Manager无法连接
Section titled “问题3：Session Manager无法连接”错误信息： “The instance you selected isn’t configured to use Session Manager”
解决方案：
- 确认IAM角色包含Session Manager所需权限
IAM角色需要包含以下权限（AmazonSSMManagedInstanceCore已包含）：
{ "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*"}- 检查VPC端点（如果使用私有子网）
如果实例在私有子网中，需要创建以下VPC端点：
com.amazonaws.region.ssmcom.amazonaws.region.ec2messagescom.amazonaws.region.ssmmessages
- 验证端点的安全组允许443端口入站流量
问题4：命令执行超时或失败
Section titled “问题4：命令执行超时或失败”解决方案：
- 检查命令输出和错误：
aws ssm get-command-invocation \ --command-id "COMMAND-ID" \ --instance-id "i-0123456789abcdef0"- 验证实例资源是否充足：
# 检查CPU使用率top
# 检查内存使用free -h
# 检查磁盘空间df -h- 增加命令超时时间：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-RunShellScript" \ --timeout-seconds 600 \ --parameters 'commands=["your-command"]'问题5：SSM Agent版本过旧
Section titled “问题5：SSM Agent版本过旧”解决方案：
查看当前版本：
Ubuntu:
snap list amazon-ssm-agentRocky Linux:
rpm -qa | grep amazon-ssm-agent更新到最新版本：
Ubuntu:
sudo snap refresh amazon-ssm-agentRocky Linux:
sudo dnf update -y amazon-ssm-agentsudo systemctl restart amazon-ssm-agent或使用Run Command批量更新：
aws ssm send-command \ --instance-ids "i-0123456789abcdef0" \ --document-name "AWS-UpdateSSMAgent"使用自动化运行手册进行故障排查
Section titled “使用自动化运行手册进行故障排查”AWS提供了自动化运行手册来诊断SSM Agent问题：
aws ssm start-automation-execution \ --document-name "AWSSupport-TroubleshootManagedInstance" \ --parameters "InstanceId=i-0123456789abcdef0"这个运行手册会自动检查：
- SSM Agent安装状态
- IAM权限配置
- 网络连接性
- 服务端点可达性
启用详细日志记录
Section titled “启用详细日志记录”如果需要更详细的日志来诊断问题：
Ubuntu系统：
- 停止SSM Agent
sudo systemctl stop snap.amazon-ssm-agent.amazon-ssm-agent.service- 修改日志配置
sudo cp /snap/amazon-ssm-agent/current/seelog.xml.template /var/snap/amazon-ssm-agent/current/seelog.xmlsudo sed -i 's/minlevel="info"/minlevel="debug"/g' /var/snap/amazon-ssm-agent/current/seelog.xml- 启动SSM Agent
sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.serviceRocky Linux系统：
- 停止SSM Agent
sudo systemctl stop amazon-ssm-agent- 修改日志配置
sudo cp /etc/amazon/ssm/seelog.xml.template /etc/amazon/ssm/seelog.xmlsudo sed -i 's/minlevel="info"/minlevel="debug"/g' /etc/amazon/ssm/seelog.xml- 启动SSM Agent
sudo systemctl start amazon-ssm-agent查看详细日志：
Rocky Linux:
sudo tail -f /var/log/amazon/ssm/amazon-ssm-agent.log