部署CloudWatch Agent

文档属性

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

任务目标

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

• 在 EC2 实例上安装并运行 CloudWatch Agent
• 收集内存、磁盘等系统级指标（EC2 默认不提供这些指标）
• 将自定义指标发送到 CloudWatch 进行监控

前置条件

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

规划说明

在动手之前，理解以下决策点：

为什么使用 IAM Role 而非 IAM User？ EC2 实例应通过 IAM Role 获取权限。Role 提供临时凭证并自动轮换，避免了在实例上存储长期凭证的安全风险。IAM User 仅适用于本地服务器场景。

为什么选择配置向导？ AWS 提供多种配置方式：手动编写 JSON、配置向导、Systems Manager Parameter Store。对于单实例或学习场景，配置向导是最佳起点——它通过交互式问答生成配置文件，降低出错概率。多实例部署场景可考虑 Parameter Store 集中管理配置。

预定义指标集选择 配置向导提供三个级别：Basic（仅内存和磁盘使用率）、Standard（增加 CPU、网络等常用指标）、Advanced（完整指标集）。对于一般监控需求，Standard 在覆盖度和成本间取得平衡。

1. 创建 IAM Role

在 AWS 控制台 中操作：

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

如需通过 Systems Manager 安装 Agent，还需附加 AmazonSSMManagedInstanceCore 策略。本文采用命令行方式，无需此策略。

2. 附加 Role 到 EC2 实例

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

3. 安装 CloudWatch Agent

SSH 连接到实例后执行：

# x86_64 架构
wget https://amazoncloudwatch-agent.s3.amazonaws.com/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb

# ARM64 架构（如 Graviton 实例）
# wget https://amazoncloudwatch-agent.s3.amazonaws.com/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb

sudo dpkg -i -E ./amazon-cloudwatch-agent.deb

其他操作系统的下载链接请参考 AWS 官方文档。

4. 配置 CloudWatch Agent

[图片占位符：运行配置向导]

运行配置向导：

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard

向导将询问一系列问题。以下为推荐选择：

1. On which OS are you planning to use the agent?
   1. linux

编号	问题	推荐选择	说明
1	On which OS	linux	自动检测
2	EC2 or On-Premises	EC2	使用 IAM Role
3	Which user to run agent	cwagent	默认即可
4	Turn on StatsD daemon	no	除非有自定义指标需求
5	Monitor metrics from collectd	no	除非已安装 collectd
6	Monitor any host metrics	yes	监控所有指标
7	Monitor per CPU metrics	yes	监控每个CPU核心
8	Add ec2 dimensions(聚合)	yes	可以监控更多指标
9	Aggregate ec2 dimensions	yes	以实例ID为聚合指标
10	Collect all metrics at high resolution(小于1分钟级)	60s	亚分钟级粒度
11	Default metrics config	Standard	平衡覆盖度与成本
12	Satisfied with the config	yes	审阅以上配置
13	Add more log into agent	no	不添加其他CloudWatchAgent日志文件
14	Monitor any log files	no	不添加其他日志文件
15	Enable to X-ray	no	不开启x-ray
16	Store config in Parameter Store	no	单实例场景选否

向导完成后，配置文件保存在： /opt/aws/amazon-cloudwatch-agent/bin/config.json

5. 启动 Agent

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -a fetch-config \
  -m ec2 \
  -s \
  -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json

参数说明：

• -a fetch-config：加载配置文件
• -m ec2：指定运行模式为 EC2
• -s：启动 Agent
• -c file:...：指定配置文件路径

6. 验证运行状态

检查 Agent 状态：

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a status

# 或者
sudo systemctl status amazon-cloudwatch-agent.service

预期输出应显示 "status": "running"。

验证指标上报（约 5 分钟后）：

1. 打开 CloudWatch Console
2. 选择 指标 > 全部指标
3. 查找 CWAgent 命名空间
4. 确认能看到 mem_used_percent、disk_used_percent 等指标

架构流程

%%{init: {"elk": true}}%%
flowchart LR
    subgraph EC2["EC2 Instance"]
        Agent["CloudWatch Agent"]
        Config["config.json"]
    end
    
    subgraph AWS["AWS Services"]
        IAM["IAM Role"]
        CW["CloudWatch"]
    end
    
    Config --> Agent
    IAM -.->|临时凭证| Agent
    Agent -->|指标/日志| CW

常见问题

Agent 无法启动，日志显示权限错误

检查 IAM Role 是否已正确附加到实例。可通过以下命令验证：

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

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

echo $RESULT

如返回 Role 名称，说明 Role 已附加。

CloudWatch 中看不到 CWAgent 指标

可能原因：

• Agent 刚启动，等待 5 分钟后刷新
• 实例无法访问 CloudWatch 端点（检查安全组出站规则和网络配置）
• 配置文件中未启用 metrics 收集

查看 Agent 日志排查问题：

sudo tail -f /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log

如何修改配置后重新加载？

修改 config.json 后，使用相同的 fetch-config 命令重启 Agent 即可。

扩展阅读

• CloudWatch Agent 配置文件详解
• CloudWatch Agent 收集的指标列表
• 使用 Systems Manager 批量部署 Agent
• CloudWatch 定价

---

架构师建议配置

场景	推荐配置
开发/测试环境	Basic 指标集，60s 采集间隔
生产环境	Standard 指标集，60s 采集间隔，启用关键日志收集
性能敏感应用	Advanced 指标集，可考虑更高分辨率（会增加成本）

核心原则：从 Standard 开始，根据实际监控需求逐步调整，避免过度收集导致不必要的成本。