Using service-linked roles for CloudWatch

Amazon CloudWatch uses AWS Identity and Access Management (IAM) service-linked roles. A service-linked role is a unique type of IAM role that is linked directly to CloudWatch. Service-linked roles are predefined by CloudWatch and include all the permissions that the service requires to call other AWS services on your behalf.

One service-linked role in CloudWatch makes setting up CloudWatch alarms that can terminate, stop, or reboot an Amazon EC2 instance without requiring you to manually add the necessary permissions. Another service-linked role enables a monitoring account to access CloudWatch data from other accounts that you specify, to build cross-account cross-Region dashboards.

CloudWatch defines the permissions of these service-linked roles, and unless defined otherwise, only CloudWatch can assume the role. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity.

You can delete the roles only after first deleting their related resources. This restriction protects your CloudWatch resources because you can't inadvertently remove permissions to access the resources.

For information about other services that support service-linked roles, see AWS Services That Work with IAM and look for the services that have Yes in the Service-Linked Role column. Choose a Yes with a link to view the service-linked role documentation for that service.

Service-linked role permissions for CloudWatch alarms EC2 actions

CloudWatch uses the service-linked role named AWSServiceRoleForCloudWatchEvents – CloudWatch uses this service-linked role to perform Amazon EC2 alarm actions.

The AWSServiceRoleForCloudWatchEvents service-linked role trusts the CloudWatch Events service to assume the role. CloudWatch Events invokes the terminate, stop, or reboot instance actions when called upon by the alarm.

The AWSServiceRoleForCloudWatchEvents service-linked role permissions policy allows CloudWatch Events to complete the following actions on Amazon EC2 instances:

The AWSServiceRoleForCloudWatchCrossAccount service-linked role permissions policy allows CloudWatch to complete the following actions:

Service-linked role permissions for CloudWatch Application Signals

CloudWatch Application Signals uses the service-linked role named AWSServiceRoleForCloudWatchApplicationSignals – CloudWatch uses this service-linked role to collect CloudWatch Logs data, X-Ray trace data, CloudWatch metrics data, and tagging data from applications that you have enabled for CloudWatch Application Signals.

The AWSServiceRoleForCloudWatchApplicationSignals service-linked role trusts CloudWatch Application Signals to assume the role. Application Signals collects the logs, traces, metrics, and tags data from your account.

The AWSServiceRoleForCloudWatchApplicationSignals has an IAM policy attached, and this policy is named CloudWatchApplicationSignalsServiceRolePolicy. This policy grants permission to CloudWatch Application Signals to collect monitoring and tagging data from other relevant AWS services. It includes permissions for Application Signals to complete the following actions:

The complete contents of CloudWatchApplicationSignalsServiceRolePolicy are as follows:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "XRayPermission",
            "Effect": "Allow",
            "Action": [
                "xray:GetServiceGraph"
            ],
            "Resource": [
                "*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "${aws:PrincipalAccount}"
                }
            }
        },
        {
            "Sid": "CWLogsPermission",
            "Effect": "Allow",
            "Action": [
                "logs:StartQuery",
                "logs:GetQueryResults"
            ],
            "Resource": [
                "arn:aws:logs:*:*:log-group:/aws/appsignals/*:*",
                "arn:aws:logs:*:*:log-group:/aws/application-signals/data:*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "${aws:PrincipalAccount}"
                }
            }
        },
        {
            "Sid": "CWListMetricsPermission",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:ListMetrics"
            ],
            "Resource": [
                "*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "${aws:PrincipalAccount}"
                }
            }
        },
        {
            "Sid": "CWGetMetricDataPermission",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:GetMetricData"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "TagsPermission",
            "Effect": "Allow",
            "Action": [
                "tag:GetResources"
            ],
            "Resource": [
                "*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "${aws:PrincipalAccount}"
                }
            }
        }
    ]
}

Service-linked role permissions for CloudWatch alarms Systems Manager OpsCenter actions

CloudWatch uses the service-linked role named AWSServiceRoleForCloudWatchAlarms_ActionSSM – CloudWatch uses this service-linked role to perform Systems Manager OpsCenter actions when a CloudWatch alarm goes into ALARM state.

The AWSServiceRoleForCloudWatchAlarms_ActionSSM service-linked role trusts the CloudWatch service to assume the role. CloudWatch alarms invoke the Systems Manager OpsCenter actions when called upon by the alarm.

The AWSServiceRoleForCloudWatchAlarms_ActionSSM service-linked role permissions policy allows Systems Manager to complete the following actions:

Service-linked role permissions for CloudWatch alarms Systems Manager Incident Manager actions

CloudWatch uses the service-linked role named AWSServiceRoleForCloudWatchAlarms_ActionSSMIncidents – CloudWatch uses this service-linked role to start Incident Manager incidents when a CloudWatch alarm goes into ALARM state.

The AWSServiceRoleForCloudWatchAlarms_ActionSSMIncidents service-linked role trusts the CloudWatch service to assume the role. CloudWatch alarms invoke the Systems Manager Incident Manager action when called upon by the alarm.

The AWSServiceRoleForCloudWatchAlarms_ActionSSMIncidents service-linked role permissions policy allows Systems Manager to complete the following actions:

Service-linked role permissions for CloudWatch cross-account cross-Region

CloudWatch uses the service-linked role named AWSServiceRoleForCloudWatchCrossAccount – CloudWatch uses this role to access CloudWatch data in other AWS accounts that you specify. The SLR only provides the assume role permission to allow the CloudWatch service to assume the role in the sharing account. It is the sharing role that provides access to data.

The AWSServiceRoleForCloudWatchCrossAccount service-linked role permissions policy allows CloudWatch to complete the following actions:

The AWSServiceRoleForCloudWatchCrossAccount service-linked role trusts the CloudWatch service to assume the role.

Service-linked role permissions for CloudWatch database Performance Insights

CloudWatch uses the service-linked role named AWSServiceRoleForCloudWatchMetrics_DbPerfInsights. – CloudWatch uses this role to retrieve Performance Insights metrics for creating alarms and snapshotting.

The AWSServiceRoleForCloudWatchMetrics_DbPerfInsights service-linked role has the AWSServiceRoleForCloudWatchMetrics_DbPerfInsightsServiceRolePolicy IAM policy attached. The contents of that policy are as follows:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"pi:GetResourceMetrics"
			],
			"Resource": "*",
			"Condition": {
				"StringEquals": {
					"aws:ResourceAccount": "${aws:PrincipalAccount}"
				}
			}
		}
	]
}

The AWSServiceRoleForCloudWatchMetrics_DbPerfInsights service-linked role trusts the CloudWatch service to assume the role.

Creating a service-linked role for CloudWatch

You do not need to manually create any of these service-linked roles. The first time you create an alarm in the AWS Management Console, the IAM CLI, or the IAM API, CloudWatch creates AWSServiceRoleForCloudWatchEvents and AWSServiceRoleForCloudWatchAlarms_ActionSSM for you.

The first time that you enable service and topology discovery, Application Signals creates AWSServiceRoleForCloudWatchApplicationSignals for you.

When you first enable an account to be a monitoring account for cross-account cross-Region functionality, CloudWatch creates AWSServiceRoleForCloudWatchCrossAccount for you.

When you first create an alarm that uses the DB_PERF_INSIGHTS metric math function, CloudWatch creates AWSServiceRoleForCloudWatchMetrics_DbPerfInsights for you.

For more information, see Creating a Service-Linked Role in the IAM User Guide.

Editing a service-linked role for CloudWatch

CloudWatch does not allow you to edit the AWSServiceRoleForCloudWatchEvents, AWSServiceRoleForCloudWatchAlarms_ActionSSM, AWSServiceRoleForCloudWatchCrossAccount, or AWSServiceRoleForCloudWatchMetrics_DbPerfInsights roles. After you create these roles, you cannot change their names because various entities might reference these roles. However, you can edit the description of these roles using IAM.

Editing a service-linked role description (IAM console)

You can use the IAM console to edit the description of a service-linked role.

Editing a service-linked role description (AWS CLI)

You can use IAM commands from the AWS Command Line Interface to edit the description of a service-linked role.

Editing a service-linked role description (IAM API)

You can use the IAM API to edit the description of a service-linked role.

Deleting a service-linked role for CloudWatch

If you no longer have alarms that automatically stop, terminate, or reboot EC2 instances, we recommend that you delete the AWSServiceRoleForCloudWatchEvents role.

If you not longer have alarms that perform Systems Manager OpsCenter actions, we recommend that you delete the AWSServiceRoleForCloudWatchAlarms_ActionSSM role.

If you delete all alarms that use the DB_PERF_INSIGHTS metric math function, we recommend that you delete the AWSServiceRoleForCloudWatchMetrics_DbPerfInsights service-linked role.

That way you don’t have an unused entity that is not actively monitored or maintained. However, you must clean up your service-linked role before you can delete it.

Cleaning up a service-linked role

Before you can use IAM to delete a service-linked role, you must first confirm that the role has no active sessions and remove any resources used by the role.

Deleting a service-linked role (IAM console)

You can use the IAM console to delete a service-linked role.

Deleting a service-linked role (AWS CLI)

You can use IAM commands from the AWS Command Line Interface to delete a service-linked role.

Deleting a service-linked role (IAM API)

You can use the IAM API to delete a service-linked role.

CloudWatch updates to AWS service-linked roles

View details about updates to AWS managed policies for CloudWatch since this service began tracking these changes. For automatic alerts about changes to this page, subscribe to the RSS feed on the CloudWatch Document history page.