aws / aws/amazon-cloudwatch-agent

Add official installation guide of CloudWatch Agent for Ubuntu

Open Beginner friendly
#2,137 1 comment 0 reactions 0 assignees View on GitHub
Stale
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.