aws / aws/amazon-cloudwatch-agent
Add official installation guide of CloudWatch Agent for Ubuntu
- Dominant language
- Go
- Stars
- 550
- Forks
- 271
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 13
Description
Current Situation: The documentation currently has a general "Installing on Linux" section. While it mentions that dpkg can be used for DEB packages, the Download Link table only provides links for Amazon Linux (RPM).
- There is no direct link provided for Ubuntu/Debian .deb packages.
- Users must guess the URL structure (e.g., .../ubuntu/amd64/latest/...) or search externally to find the correct package.
- The instructions do not specify how to handle architecture differences (amd64 vs arm64) for Ubuntu specifically.
Proposed Solution: Add a dedicated subsection titled "Installing on Ubuntu" (similar to the existing Amazon Linux, Windows, and macOS sections) that includes:
Prerequisites
1. IAM Role Setup
First, ensure your EC2 instance has the proper IAM role with the CloudWatchAgentServerPolicy:
Go to [IAM Console ](https://console.aws.amazon.com/iam/home#/roles) → Roles → Create role
Select "AWS service" → "EC2"
Attach the policy: CloudWatchAgentServerPolicy
Create the role and attach it to your EC2 instance
2. Required Permissions
The IAM role should include permissions for:
logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents
cloudwatch:PutMetricData
Installation Steps
Step 1: Download and Install the CloudWatch Agent
For x86-64 architecture:
wget https://amazoncloudwatch-agent.s3.amazonaws.com/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb
sudo dpkg -i -E ./amazon-cloudwatch-agent.deb
For ARM64 architecture:
wget https://amazoncloudwatch-agent.s3.amazonaws.com/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb
sudo dpkg -i -E ./amazon-cloudwatch-agent.deb
Step 2: Configure the CloudWatch Agent
You have two options for configuration:
Option A: Using the Configuration Wizard
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
The wizard will ask you to configure:
Metrics to collect (CPU, memory, disk, network)
Log files to monitor (system logs, application logs)
Log groups and streams
Region settings
Option B: Manual Configuration
Create a configuration file at /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json:
{
"agent": {
"metrics_collection_interval": 60,
"run_as_user": "cwagent"
},
"logs": {
"logs_collected": {
"files": {
"collect_list": [
{
"file_path": "/var/log/syslog",
"log_group_name": "/aws/ec2/syslog",
"log_stream_name": "{instance_id}",
"timezone": "UTC"
},
{
"file_path": "/var/log/auth.log",
"log_group_name": "/aws/ec2/auth",
"log_stream_name": "{instance_id}",
"timezone": "UTC"
}
]
}
}
},
"metrics": {
"namespace": "CWAgent",
"metrics_collected": {
"cpu": {
"measurement": [
"cpu_usage_idle",
"cpu_usage_iowait",
"cpu_usage_user",
"cpu_usage_system"
],
"metrics_collection_interval": 60
},
"disk": {
"measurement": [
"used_percent"
],
"metrics_collection_interval": 60,
"resources": [
"*"
]
},
"diskio": {
"measurement": [
"io_time"
],
"metrics_collection_interval": 60,
"resources": [
"*"
]
},
"mem": {
"measurement": [
"mem_used_percent"
],
"metrics_collection_interval": 60
}
}
}
}
Step 3: Start the CloudWatch 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/etc/amazon-cloudwatch-agent.json
Step 4: Verify Installation
Check the agent status:
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-m ec2 \
-a status
Contributor guide
Research direction
Start with the existing “Installing on Linux” documentation and compare its Amazon Linux, Windows, and macOS sections. Add an Ubuntu subsection covering IAM prerequisites, amd64 and arm64 package links, installation, configuration, startup, and status verification; done means Ubuntu users can follow the guide without guessing URLs or architecture-specific steps.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, linux, ubuntu
- Domain
- cloud, devops, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100