How do I configure on-premises servers to use temporary credentials with SSM Agent and unified CloudWatch Agent?

Resolution

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

The unified CloudWatch agent uses AWS Identity and Access Management (IAM) credentials that are specified in a configuration file for performance monitoring and management. However, for enhanced security, the agent might rotate credentials instead of storing them in local files. SSM Agent allows your on-premises host to assume an IAM role, and the CloudWatch agent uses this role to publish metrics and logs to CloudWatch.

Configure your on-premises servers to use only temporary credentials

Complete the following steps:

1. Integrate your on-premises host with AWS System Manager. For more information, see Managing nodes in hybrid and multicloud environments with Systems Manager.

2. Attach the CloudWatchAgentServerPolicy policy to the IAM service role. For instructions, see Using the AWS Management Console to create an IAM service role for Systems Manager hybrid activations.

3. Install or update the AWS CLI.

4. Run the following get-caller-identity command to verify that the IAM role is attached to your on-premises host:

   aws sts get-caller-identity

   Example output:

   {
       "UserId": "AROAJXQ3RVCBOTUDZ2AWM:mi-070c8d5758243078f",
       "Account": "123456789012",
       "Arn": "arn:aws:sts::444455556666:assumed-role/SSMServiceRole/mi-070c8d5758243078f"
   }

5. Confirm that you correctly installed the unified CloudWatch agent.

6. Modify the common-config.toml file to point to the credentials that the SSM Agent generated. For instructions, see Modifying the common configuration and named profile for CloudWatch agent.
   Note: The SSM Agent refreshes the credentials every 30 minutes.
   For Linux, example common.config.toml file path:

   /opt/aws/amazon-cloudwatch-agent/etc/common-config.toml

   Example output:

   [credentials]
     shared_credential_profile = "default"
     shared_credential_file = "/root/.aws/credentials"

   For Windows, example common-config.toml file path:

   $Env:ProgramData\Amazon\AmazonCloudWatchAgent\common-config.toml

   Example output:

   [credentials]  shared_credential_profile = "default"
     shared_credential_file = "C:\\Windows\\System32\\config\\systemprofile\\.aws\\credentials"

7. Configure your AWS Region in the shared_credential_file credentials file that the SSM Agent references:

   cat /root/.aws/config
    [default]
   region = eu-west-1

   Note: Replace eu-west-1 with your Region.

8. For Linux hosts, configure your permissions for the CloudWatch agent to allow the unified CloudWatch agent to read the SSM Agent credentials file. The unified CloudWatch agent runs as the root user by default. If you configure the CloudWatch agent to run as a non-privileged user with the run_as_user parameter, then grant this user access to the credentials file. For instructions, see Running the CloudWatch agent as a different user.
   Important: For Windows hosts, skip this step. Both agents run as SYSTEM user.

9. Open Services on your Windows server, and then choose Amazon CloudWatch Agent Properties to configure the CloudWatch agent service startup.
   From Properties, select the Startup type dropdown list, and then choose Automatic (Delayed Start).
   Note: The Automatic (Delayed Start) startup type automatically starts the CloudWatch agent service after the SSM Agent service.

Related information

Download the CloudWatch agent on an on-premises server

How do I install and configure the unified CloudWatch agent to send metrics and logs from my EC2 instance to CloudWatch?