Using service-linked roles for CloudWatch RUM - Amazon CloudWatch
Service-linked role permissions for RUMCreating a service-linked role for RUMEditing a service-linked role for RUM Deleting a service-linked role for RUM
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using service-linked roles for CloudWatch RUM

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

RUM defines the permissions of the service-linked role, and unless defined otherwise, only RUM 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 role only after first deleting its related resources. This restriction protects your RUM resources because you can't inadvertently remove permissions to access the resources.

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

Service-linked role permissions for RUM

RUM uses the service-linked role named AWSServiceRoleForCloudWatchRUM – this role allows RUM to send Amazon X-Ray trace data into your account, for app monitors that you enable X-Ray tracing for.

The AWSServiceRoleForCloudWatchRUM service-linked role trusts the X-Ray service to assume the role. X-Ray sends the trace data to your account.

The AWSServiceRoleForCloudWatchRUM service-linked role has an IAM policy attached named AmazonCloudWatchRUMServiceRolePolicy. This policy grants permission to CloudWatch RUM to publish monitoring data to other relevant Amazon services. It includes permissions that allow RUM to complete the following actions:

  • xray:PutTraceSegments

  • cloudwatch:PutMetricData

The complete contents of AmazonCloudWatchRUMServiceRolePolicy are as follows.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"xray:PutTraceSegments"
			],
			"Resource": [
				"*"
			]
		},
		{
			"Effect": "Allow",
			"Action": "cloudwatch:PutMetricData",
			"Resource": "*",
			"Condition": {
				"StringLike": {
					"cloudwatch:namespace": [
						"RUM/CustomMetrics/*",
						"AWS/RUM"
					]
				}
			}
		}
	]
}

Creating a service-linked role for RUM

You do not need to manually create the service-linked role for CloudWatch RUM. The first time that you create an app monitor with X-Ray tracing enabled, or update an app monitor to use X-Ray tracing, RUM creates AWSServiceRoleForCloudWatchRUM for you.

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

Editing a service-linked role for RUM

CloudWatch RUM does not allow you to edit the AWSServiceRoleForCloudWatchRUM role. 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.

To edit the description of a service-linked role (console)

  1. In the navigation pane of the IAM console, choose Roles.

  2. Choose the name of the role to modify.

  3. To the far right of Role description, choose Edit.

  4. Type a new description in the box, and choose Save.

Editing a service-linked role description (Amazon CLI)

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

To change the description of a service-linked role (Amazon CLI)

  1. (Optional) To view the current description for a role, use the following commands:

    $ aws iam get-role --role-name role-name

    Use the role name, not the ARN, to refer to roles with the Amazon CLI commands. For example, if a role has the following ARN: arn:aws-cn:iam::123456789012:role/myrole, you refer to the role as myrole.

  2. To update a service-linked role's description, use the following command:

    $ aws iam update-role-description --role-name role-name --description description

Editing a service-linked role description (IAM API)

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

To change the description of a service-linked role (API)

  1. (Optional) To view the current description for a role, use the following command:

    GetRole

  2. To update a role's description, use the following command:

    UpdateRoleDescription

Deleting a service-linked role for RUM

If you no longer have app monitors with X-Ray enabled, we recommend that you delete the AWSServiceRoleForCloudWatchRUM 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.

To check whether the service-linked role has an active session in the IAM console

  1. Open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane, choose Roles. Choose the name (not the check box) of the AWSServiceRoleForCloudWatchRUM role.

  3. On the Summary page for the selected role, choose Access Advisor and review the recent activity for the service-linked role.

    Note

    If you are unsure whether RUM is using the AWSServiceRoleForCloudWatchRUM role, try to delete the role. If the service is using the role, then the deletion fails and you can view the Regions where the role is being used. If the role is being used, then you must wait for the session to end before you can delete the role. You cannot revoke the session for a service-linked role.

Deleting a service-linked role (IAM console)

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

To delete a service-linked role (console)

  1. Open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane, choose Roles. Select the check box next to the name of the role you want to delete, not the name or row itself.

  3. For Role actions, choose Delete role.

  4. In the confirmation dialog box, review the service last accessed data, which shows when each of the selected roles last accessed an Amazon service. This helps you to confirm whether the role is currently active. To proceed, choose Yes, Delete.

  5. Watch the IAM console notifications to monitor the progress of the service-linked role deletion. Because the IAM service-linked role deletion is asynchronous, the deletion task can succeed or fail after you submit the role for deletion. If the task fails, choose View details or View Resources from the notifications to learn why the deletion failed. If the deletion fails because there are resources in the service that are being used by the role, then the reason for the failure includes a list of resources.

Deleting a service-linked role (Amazon CLI)

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

To delete a service-linked role (Amazon CLI)

  1. Because a service-linked role cannot be deleted if it is being used or has associated resources, you must submit a deletion request. That request can be denied if these conditions are not met. You must capture the deletion-task-id from the response to check the status of the deletion task. Type the following command to submit a service-linked role deletion request:

    $ aws iam delete-service-linked-role --role-name service-linked-role-name

  2. Type the following command to check the status of the deletion task:

    $ aws iam get-service-linked-role-deletion-status --deletion-task-id deletion-task-id

    The status of the deletion task can be NOT_STARTED, IN_PROGRESS, SUCCEEDED, or FAILED. If the deletion fails, the call returns the reason that it failed so that you can troubleshoot.

Deleting a service-linked role (IAM API)

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

To delete a service-linked role (API)

  1. To submit a deletion request for a service-linked role, call DeleteServiceLinkedRole. In the request, specify the role name that you want to delete.

    Because a service-linked role cannot be deleted if it is being used or has associated resources, you must submit a deletion request. That request can be denied if these conditions are not met. You must capture the DeletionTaskId from the response to check the status of the deletion task.

  2. To check the status of the deletion, call GetServiceLinkedRoleDeletionStatus. In the request, specify the DeletionTaskId.

    The status of the deletion task can be NOT_STARTED, IN_PROGRESS, SUCCEEDED, or FAILED. If the deletion fails, the call returns the reason that it failed so that you can troubleshoot.