Installing CloudWatch Agent on Additional Instances Using Your Agent Configuration
After you have a CloudWatch agent configuration saved in Parameter Store, you can use it when you install the agent on other servers.
Topics
Create an IAM Role for Systems Manager and the CloudWatch Agent
An IAM role for the instance profile is required when you install the CloudWatch agent on an Amazon EC2 instance. This role enables the CloudWatch agent to perform actions on the instance. Use the role you created earlier that includes just the permissions needed for installing and running the agent. This role may be called CloudWatchAgentServerPolicy.
Attach this role to the instance where you install the CloudWatch agent. For more information, see Attaching an IAM Role to an Instance in the Amazon EC2 User Guide for Windows Instances.
Download the CloudWatch Agent Package on an Amazon EC2 Instance
You can download the CloudWatch agent package using either Systems Manager Run Command or an Amazon S3 download link.
Download the CloudWatch Agent on an Amazon EC2 Instance Using Systems Manager
Before you can use Systems Manager to install the CloudWatch agent, you must make sure that the instance is configured correctly for Systems Manager.
Install or Update the SSM Agent
On an Amazon EC2 instance, the CloudWatch agent requires that the instance is running version 2.2.93.0 or later. Before you install the CloudWatch agent, update or install the SSM Agent on the instance if you haven't already done so.
For information about installing or updating the SSM Agent on an instance running Linux, see Installing and Configuring the SSM Agent on Linux Instances in the AWS Systems Manager User Guide.
For information about installing or updating the SSM Agent, see Installing and Configuring SSM Agent in the AWS Systems Manager User Guide.
(Optional) Verify Systems Manager Prerequisites
Before you use Systems Manager Run Command to install and configure the CloudWatch agent, verify that your instances meet the minimum Systems Manager requirements. For more information, see Systems Manager Prerequisites in the AWS Systems Manager User Guide.
Verify Internet Access
Your Amazon EC2 instances must have outbound internet access in order to send data to CloudWatch or CloudWatch Logs. For more information about how to configure internet access, see Internet Gateways in the Amazon VPC User Guide.
Download the CloudWatch Agent Package
Systems Manager Run Command enables you to manage the configuration of your instances. You specify a Systems Manager document, specify parameters, and execute the command on one or more instances. The SSM Agent on the instance processes the command and configures the instance as specified.
To download the CloudWatch agent using Run Command
-
Open the Systems Manager console at https://console.aws.amazon.com/systems-manager/.
-
In the navigation pane, choose Run Command.
-or-
If the AWS Systems Manager home page opens, scroll down and choose Explore Run Command.
-
Choose Run command.
-
In the Command document list, choose AWS-ConfigureAWSPackage.
-
In the Targets area, choose the instance on which to install the CloudWatch agent. If you do not see a specific instance, it might not be configured for Run Command. For more information, see Systems Manager Prerequisites in the AWS Systems Manager User Guide.
-
In the Action list, choose Install.
-
In the Name box, type AmazonCloudWatchAgent.
-
Leave Version set to latest to install the latest version of the agent.
-
Choose Run.
-
Optionally, in the Targets and outputs areas, select the button next to an instance name and choose View output. Systems Manager should show that the agent was successfully installed.
Download the CloudWatch Agent Package on an Amazon EC2 Instance Using an S3 Download Link
You can use an Amazon S3 download link to download the CloudWatch agent package on an Amazon EC2 instance server. Choose the download link from this table, depending on your architecture and platform.
Arch | Platform | Download Link | Signature File Link |
---|---|---|---|
amd64 |
Amazon Linux and Amazon Linux 2 |
https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm.sig |
amd64 |
Centos |
https://s3.amazonaws.com/amazoncloudwatch-agent/centos/amd64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/centos/amd64/latest/amazon-cloudwatch-agent.rpm.sig |
amd64 |
Redhat |
https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/amd64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/amd64/latest/amazon-cloudwatch-agent.rpm.sig |
amd64 |
SUSE |
https://s3.amazonaws.com/amazoncloudwatch-agent/suse/amd64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/suse/amd64/latest/amazon-cloudwatch-agent.rpm.sig |
amd64 |
Debian |
https://s3.amazonaws.com/amazoncloudwatch-agent/debian/amd64/latest/amazon-cloudwatch-agent.deb |
https://s3.amazonaws.com/amazoncloudwatch-agent/debian/amd64/latest/amazon-cloudwatch-agent.deb.sig |
amd64 |
Ubuntu |
https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb |
https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb.sig |
amd64 |
Windows |
https://s3.amazonaws.com/amazoncloudwatch-agent/windows/amd64/latest/amazon-cloudwatch-agent.msi |
https://s3.amazonaws.com/amazoncloudwatch-agent/windows/amd64/latest/amazon-cloudwatch-agent.msi.sig |
arm64 |
Amazon Linux 2 |
https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/arm64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/arm64/latest/amazon-cloudwatch-agent.rpm.sig |
arm64 |
Redhat |
https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/arm64/latest/amazon-cloudwatch-agent.rpm |
https://s3.amazonaws.com/amazoncloudwatch-agent/redhat/arm64/latest/amazon-cloudwatch-agent.rpm.sig |
arm64 |
Ubuntu |
https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb |
https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/arm64/latest/amazon-cloudwatch-agent.deb.sig |
To use the command line to install the CloudWatch agent on an Amazon EC2 instance
-
Download the CloudWatch agent. For a Linux server, type the following. For
download-link
, use the appropriate download link from the previous table.wget
download-link
For a server running Windows Server, download the following file:
https://s3.amazonaws.com/amazoncloudwatch-agent/windows/amd64/latest/amazon-cloudwatch-agent.msi
-
After you have downloaded the package, you can optionally use a GPG signature file to verify the package signature. For more information, see Verify the Signature of the CloudWatch Agent Package.
-
Install the package. If you downloaded an RPM package on a Linux server, change to the directory containing the package and type the following:
sudo rpm -U ./amazon-cloudwatch-agent.rpm
If you downloaded a DEB package on a Linux server, change to the directory containing the package and type the following:
sudo dpkg -i -E ./amazon-cloudwatch-agent.deb
If you downloaded an MSI package on a server running Windows Server, change to the directory containing the package, and type the following:
msiexec /i amazon-cloudwatch-agent.msi
This command also works from within PowerShell. For more information about MSI command options, see Command-Line Options in the Microsoft Windows documentation.
(Optional) Modify the Common Configuration and Named Profile for CloudWatch Agent
The CloudWatch agent package you have downloaded includes a configuration file called
common-config.toml
. You can use this file to specify proxy,
credential, and Region information. On a server running Linux, this file is in the
/opt/aws/amazon-cloudwatch-agent/etc
directory. On a server running Windows
Server, this file is in the C:\ProgramData\Amazon\AmazonCloudWatchAgent
directory.
The default common-config.toml
is as follows:
When you install the CloudWatch agent on an Amazon EC2 instance, modify this file only if you need to specify proxy settings or if the agent should send metrics to CloudWatch in a different Region than where the instance is located.
# This common-config is used to configure items used for both ssm and cloudwatch access ## Configuration for shared credential. ## Default credential strategy will be used if it is absent here: ## Instance role is used for EC2 case by default. ## AmazonCloudWatchAgent profile is used for onPremise case by default. # [credentials] # shared_credential_profile = "{profile_name}" # shared_credential_file= "{file_name}" ## Configuration for proxy. ## System-wide environment-variable will be read if it is absent here. ## i.e. HTTP_PROXY/http_proxy; HTTPS_PROXY/https_proxy; NO_PROXY/no_proxy ## Note: system-wide environment-variable is not accessible when using ssm run-command. ## Absent in both here and environment-variable means no proxy will be used. # [proxy] # http_proxy = "{http_url}" # https_proxy = "{https_url}" # no_proxy = "{domain}"
All lines are commented out initially. To set the credential profile or proxy
settings, remove the #
from that line and specify a value. You can edit this
file manually, or by using the RunShellScript
Run Command in Systems Manager:
-
shared_credential_profile To have the CloudWatch agent send metrics to CloudWatch in the same Region where the instance is located, modify this line or attach an IAM role with the proper permissions to the instance. If you attach the IAM role, you don't need to use the
aws configure
command to create a named profile for the agent.Otherwise, you can use this line to specify the named profile that CloudWatch agent is to use in the AWS credentials and AWS config files. If you do so, CloudWatch agent uses the credential and the Region settings in that named profile.
-
shared_credential_file Use this line to specify a path to a file containing credentials to use, if you don't want to use the default path.
-
proxy settings If your servers use HTTP or HTTPS proxies to contact AWS services, specify those proxies in the
http_proxy
andhttps_proxy
fields. If there are URLs that should be excluded from proxying, specify them in theno_proxy
field, separated by commas.
After modifying common-config.toml
, if you need to specify
credential and Region information for the CloudWatch agent, create a named profile
for the CloudWatch
agent in the AWS credentials and AWS config files. When you create this profile, do
so
as the root or administrator. Following is an example of this profile in the credentials
file:
[AmazonCloudWatchAgent] aws_access_key_id =
my_access_key
aws_secret_access_key =my_secret_key
For my_access_key
and my_secret_key
, use the keys from the
IAM user that does not have the permissions to write to Systems Manager Parameter
Store. For more
information about the IAM users needed for the CloudWatch agent, see Create IAM Users to Use with
CloudWatch Agent on On-premises Servers.
Following is an example of the profile for the configuration file:
[AmazonCloudWatchAgent] region = us-west-1
Following is an example of using the aws configure
command to create a
named profile for the CloudWatch agent. This example assumes that you are using the
default
profile name of AmazonCloudWatchAgent
.
To create the AmazonCloudWatchAgent profile for the CloudWatch agent
-
On a Linux server, type the following command and follow the prompts:
sudo aws configure --profile AmazonCloudWatchAgent
On Windows Server, open PowerShell as an administrator, and type the following command and follow the prompts:
aws configure --profile AmazonCloudWatchAgent
Start the CloudWatch Agent
You can start the agent using Systems Manager Run Command or the command line.
Start the CloudWatch Agent Using Systems Manager Run Command
Follow these steps to start the agent using Systems Manager Run Command.
To start the CloudWatch agent using Run Command
-
Open the Systems Manager console at https://console.aws.amazon.com/systems-manager/.
-
In the navigation pane, choose Run Command.
-or-
If the AWS Systems Manager home page opens, scroll down and choose Explore Run Command.
-
Choose Run command.
-
In the Command document list, choose AmazonCloudWatch-ManageAgent.
-
In the Targets area, choose the instance where you installed the CloudWatch agent.
-
In the Action list, choose configure.
-
In the Optional Configuration Source list, choose ssm.
-
In the Optional Configuration Location box, type the name of the agent configuration file that you created and saved to Systems Manager Parameter Store, as explained in Create the CloudWatch Agent Configuration File.
-
In the Optional Restart list, choose yes to start the agent after you have finished these steps.
-
Choose Run.
-
Optionally, in the Targets and outputs areas, select the button next to an instance name and choose View output. Systems Manager should show that the agent was successfully started.
Start the CloudWatch Agent on an Amazon EC2 Instance Using the Command Line
Follow these steps to use the command line to install the CloudWatch agent on an Amazon EC2 instance.
To use the command line to start the CloudWatch agent on an Amazon EC2 instance
-
In this command,
-a fetch-config
causes the agent to load the latest version of the CloudWatch agent configuration file, and-s
starts the agent.Linux: Type the following if you saved the configuration file in the Systems Manager Parameter Store:
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c ssm:
configuration-parameter-store-name
-sLinux: Type the following if you saved the configuration file on the local computer:
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:
configuration-file-path
-sWindows Server: If you saved the agent configuration file in Systems Manager Parameter Store, use the following command. From the PowerShell console, type the following:
./amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c ssm:
configuration-parameter-store-name
-sWindows Server: If you saved the agent configuration file on the local computer, use the following command. From the PowerShell console, type the following:
./amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:
configuration-file-path
-s