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

3 minute read

I have a hybrid environment with on-premises servers that use AWS Systems Manager Agent (SSM Agent) and the unified Amazon CloudWatch Agent installed. How can I configure my on-premises servers to use only temporary credentials?


Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

The unified CloudWatch Agent can be installed to on-premises hosts for improved performance monitoring. You can do this by specifying AWS Identity and Accesses Management (IAM) credentials that are written to a configuration file.

However, some use cases might require the greater security of rotating credentials that aren’t saved to local files.

In this more secure deployment scenario, the SSM Agent allows the on-premises host to assume an IAM role. Then the unified CloudWatch Agent can be configured to use this IAM role to publish metrics and logs to CloudWatch.

To configure your on-premises servers to use only temporary credentials:

1.    Integrate the on-premises host with AWS System Manager.

2.    Attach the AWS managed IAM CloudWatchAgentServerPolicy to the IAM Service Role for a Hybrid Environment. Now the unified CloudWatch Agent has the permissions to post metrics and logs to CloudWatch.

3.    Install or update the AWS CLI.

4.    Confirm that the IAM Role is attached to the on-premises host:

$ aws sts get-caller-identity
    "UserId": "AROAJXQ3RVCBOTUDZ2AWM:mi-070c8d5758243078f",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/SSMServiceRole/mi-070c8d5758243078f"

5.    Install the unified CloudWatch Agent.

6.    Update the common-config.toml file to:

  • Point to the credentials generated by SSM Agent
  • Set a proxy configuration (if applicable)

Note: These credentials are refreshed by the SSM Agent every 30 minutes.


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


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

7.    Choose the AWS Region that the unified CloudWatch Agent metrics will post to.

8.    Add the region in the credential file referenced by the SSM Agent in Step 5. This corresponds to the file associated with the shared_credential_file.

$ cat /root/.aws/config 
region = "eu-west-1"

Note: Be sure to replace eu-west-1 with your target Region.

9.    Depending on your host operating system, you might have to update permissions to allow the unified CloudWatch Agent to read the SSM Agent credentials file. Windows hosts run both agents as SYSTEM user and no further action is required.

For Linux hosts, by default the unified CloudWatch Agent runs as the root user. The unified CloudWatch Agent can be configured to run as a non-privileged user with the run_as_user option. When using this option, you must grant the unified CloudWatch Agent access to the credentials file.

10.    (Windows only) Change the Startup type of the unified CloudWatch Agent service to Automatic (Delayed). This starts the unified CloudWatch Agent service after the SSM Agent service during boot.

Related information

Setting up AWS Systems Manager for hybrid environments

Download the CloudWatch agent on an on-premises server

Install and configure the unified CloudWatch Agent to push metrics and logs from an EC2 instance to CloudWatch

AWS OFFICIALUpdated 8 months ago