How to Use AWS Systems Manager to Install CloudWatch Agents on Multiple Instances at Once (Linux & Windows)

Managing a large number of instances that require monitoring can be challenging, especially if the CloudWatch Agent needs to be manually installed on each instance. Traditionally, without AWS Systems Manager (SSM), you would have to SSH or RDP into every instance individually, which is time-consuming and inefficient.

With AWS Systems Manager, you can quickly and efficiently install the CloudWatch Agent on multiple instances at once. The steps below outline how to use SSM to install CloudWatch Agents on both Linux and Windows instances.

Note: The installation steps are the same for both Windows and Linux systems. The only difference lies in the CloudWatch Agent configuration content, which we will cover in detail below.

Step-by-Step Guide to Install CloudWatch Agents:

Step 1: Create or Modify an IAM Role for the Instances

To allow instances to communicate with CloudWatch and Systems Manager, you need to either create a new IAM role or modify an existing IAM role to attach the following two policies:

• CloudWatchAgentServerPolicy
• AmazonSSMManagedInstanceCore

Refer to the AWS documentation for detailed steps on creating an IAM role here.

Step 2: Attach the IAM Role to the Instances

1. Navigate to the EC2 console.
2. Select the target instance(s).
3. Choose Actions → Security → Modify IAM role.
4. Select the IAM role created in Step 1.
5. Click Update IAM role.

Note: At this time, AWS Console does not support attaching IAM roles to multiple instances in one action. 

Alternatively, you can use the AWS CLI and a simple for loop to attach the instance profile to multiple instances at once. Here's an example:

instance_ids=("i-022d145xxxxxx15e6" "i-09a2158xxxxxxd2b2")  # Add more instance IDs
profile_name="your-iam-role-name"  # Set your instance profile name here

for instance_id in "${instance_ids[@]}"; do
  aws ec2 associate-iam-instance-profile \
    --instance-id $instance_id \
    --iam-instance-profile Name=$profile_name
done

Step 3: Install the CloudWatch Agent Using SSM

1. Go to the AWS Systems Manager console and select Run Command.
2. In the Command document section, select AWS-ConfigureAWSPackage
3. In the Command parameters, input AmazonCloudWatchAgent in the Name field.
4. In the Targets section, choose the instances you want to install the agent on:
   • You can manually select instances or specify instance tags to target a group of instances.
   • Be patient, as it may take 10+ minutes for all instances to appear.
5. (Optional) Save command output to the CloudWatch logs or an S3 bucket.
6. Click Run to execute the command.

Once the command runs successfully, the CloudWatch Agent will normally be installed on all selected instances within 1-2 minutes.

Check the screenshot to know more:

Step 4: Create a CloudWatch Agent Configuration in Parameter Store

Now that the agent is installed, you need to create a configuration file for it. Make sure to test your CloudWatch configuration to ensure it works as expected before deploying it to multiple instances.

1. In the SSM Console, navigate to Parameter Store and click Create parameter.
2. Name your parameter e.g., AmazonCloudWatch-WinConfig.
3. In the Value field, paste your CloudWatch Agent configuration file in JSON format.

Here are sample configuration files for Linux and Windows:

• Linux CloudWatch Agent Configuration:
  (This sample configuration collects disk usage (used_percent) and memory usage (mem_used_percent) metrics from Linux instances and pushes them to CloudWatch every 60 seconds.)

{
    "metrics": {
        "aggregation_dimensions": [
            [
                "InstanceId"
            ]
        ],
        "metrics_collected": {
            "disk": {
                "measurement": [
                    "used_percent"
                ],
                "metrics_collection_interval": 60,
                "resources": [
                    "*"
                ]
            },
            "mem": {
                "measurement": [
                    "mem_used_percent"
                ],
                "metrics_collection_interval": 60
            }
        },
        "append_dimensions": {
            "InstanceId": "${aws:InstanceId}"
        }
    }
}

• Windows CloudWatch Agent Configuration:
  (This sample configuration collects various performance metrics from Windows instances, including disk usage (% Free Space), and memory usage (% Committed Bytes In Use). These metrics are pushed to CloudWatch every 60 seconds)

{
    "metrics": {
        "aggregation_dimensions": [
            [
                "InstanceId"
            ]
        ],
        "metrics_collected": {
            "LogicalDisk": {
                "measurement": [
                    "% Free Space"
                ],
                "metrics_collection_interval": 60,
                "resources": [
                    "*"
                ]
            },
            "Memory": {
                "measurement": [
                    "% Committed Bytes In Use"
                ],
                "metrics_collection_interval": 60
            }
        },
        "append_dimensions": {
            "InstanceId": "${aws:InstanceId}"
        }
    }
}

    4. Click Create parameter to save.

Check the screenshot to know more:

Step 5: Start the CloudWatch Agent

Now, it's time to start the CloudWatch Agent service on your instances using the configuration you just created.

1. Go back to Run Command in the SSM Console.
2. In the Command document section, choose AmazonCloudWatch-ManageAgent.
3. In the Command parameters section, specify the Optional Configuration Location (e.g., AmazonCloudWatch-WinConfig).
4. Select the target instances.
5. (Optional) Save command output to the CloudWatch logs or an S3 bucket.
6. Click Run.

Check the screenshot to know more:

After the command runs successfully, you should see the metrics appear in the CloudWatch CWAgent namespace. Depending on the metrics_collection_interval you configured, it may take a few minutes for the metrics to appear in the CloudWatch console.

---

How to Edit or Modify CloudWatch Agent Configurations

If you need to modify the configuration file for the CloudWatch Agent and then deploy the new configuration to multiple instances, follow these steps:

1. Navigate to Parameter Store in the SSM Console.
2. Click Edit on the parameter you want to modify.
3. Update the JSON content in the Value field and save changes.
4. Go to the Command history tab in the Run Command section to locate the command you used to start the agent, or create a new command by following the steps outlined above.
5. Use the Rerun option to deploy the updated configuration to the instances.

Check the screenshot to know more:

---

By following these steps, you can efficiently install, modify, and manage CloudWatch Agents on multiple instances at ounce. If you have any questions or need further assistance, feel free to reach out to AWS Support.