How do I install and configure the unified CloudWatch Agent with Systems Manager?

Resolution

To install and configure the unified CloudWatch Agent with Systems Manager, complete the following steps:

Create and attach the IAM role

Create an AWS Identity Access Management (IAM) role to provide permissions for CloudWatch and SSM Agents and attach the role to the required instances:

1. Open the IAM console.
2. Choose Roles, and then select Create role.
3. For Select type of trusted entity, choose AWS service.
4. In Common use cases, choose EC2, and then choose Next.
5. In the list of policies, select the CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore check box, and then choose Next.
6. For Role name, enter a name for the role, such as CloudWatchAgentServerRole.
7. (Optional) Provide a role description.
8. Confirm that CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore appear next to Policies.
9. Choose Create role.
10. Attach the IAM role to the Amazon Elastic Compute Cloud (Amazon EC2) instance.

For on-premises servers, see Create IAM users to use with the CloudWatch agent on on-premises servers.

Use Systems Manager to download and install the unified CloudWatch Agent

Before you begin, complete the following steps:

• Install AWS Systems Manager Agent (SSM Agent) version 3.2.1705.0 or later on the instance. To verify the version on the instance, see Checking the SSM version number.
• Make sure that the Amazon EC2 instance has an Online status and is managed by SSM Agent. To verify that the instance is managed by SSM Agent, see Verify the status of SSM Agent.
• If your instance is private, then use AWS PrivateLink to configure endpoints for use by the SSM and CloudWatch Agents. This configuration requires access to SSM, monitoring, logs, and Amazon EC2 endpoints.

After you complete the preceding steps, use Systems Manager to download and install the CloudWatch agent.

Create and modify the agent configuration file

To create and modify the agent configuration file, use the wizard to create the CloudWatch agent configuration file:

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

On a server running Windows Server, run the following commands to launch the wizard:

cd "C:\Program Files\Amazon\AmazonCloudWatchAgent"

.\amazon-cloudwatch-agent-config-wizard.exe

When the wizard completes, the agent configuration file is stored at /opt/aws/amazon-cloudwatch-agent/bin/config.json on Linux servers and at C:\Program Files\Amazon\AmazonCloudWatchAgent on Windows servers. You can manually edit the file to add or remove metrics or logs.

Note: If you plan to use Systems Manager to install and configure the agent, be sure to answer Yes when prompted to store the file in the Systems Manager Parameter Store. If you don't use the SSM Agent to install the CloudWatch agent, then you can choose to store the file in Parameter Store. To store the file in Parameter Store, use an IAM role with the appropriate permissions. For more information, see Create IAM roles and users for use with the CloudWatch agent.

Start the CloudWatch agent

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

To start the CloudWatch agent, use either the Systems Manager Run Command or the AWS Command Line Interface (AWS CLI). For more information, see Start the CloudWatch agent.

Note: When you use the SSM AmazonCloudWatch-ManageAgent command to deploy an Agent configuration that's stored in Parameter Store, then multiple instances can be deployed simultaneously. After deployment, if any changes are made to the Agent configuration in Parameter Store, then the AmazonCloudWatch-ManageAgent command must be issued again. To issue the command, use the Configure action option in the command to make sure that the configuration changes occur on the target instances.

Related information

Installing the CloudWatch agent on EC2 instances using your agent configuration

Troubleshooting the CloudWatch agent

How can I send memory and disk metrics from my EC2 instances to CloudWatch?