Resource tag-sync and required permissions

An automatic tag-synchronization of application resources (tag-sync) is an application resource management strategy that works by automatically adding and removing The awsApplication tag from resources to manage their inclusion in an application. When you create a tag-sync in the application, you specify a tag key-value pair to sync to the application, such as Project:Blue. The tag-sync then adds any resources tagged with Project:Blue to the application by adding the awsApplication tag to those resources.

When you perform the following tasks, AWS adds all resources tagged with the Project:Blue tag to the application by applying the awsApplication tag to those resources:

After you configure the tag-sync, it continuously manages the application's resources, adding or removing resources as they are tagged or untagged with the specified key-value pair.

When the tag-sync is active, if you tag a resource with the Project:Blue tag, the tag-sync adds that resource to the application by applying the awsApplication tag to it.

When you remove the Project:Blue tag from a resource, the tag-sync removes the resource from the application by removing the awsApplication tag.

Tag-sync required permissions

Creating and managing application tag-sync tasks requires you to specify an IAM role that has permissions to tag and untag application resources. This role must also have a trust policy attached that allows AWS Resource Groups to assume the role and perform these tasks on your behalf.

Sample trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Allow",
      "Principal": {
        "Service": "resource-groups.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

After specifying the trust policy for the role, you must give the role permissions to tag and untag application resources. To easily and effectively apply the necessary permissions to the role, we recommend using both the AWS Resource Groups ResourceGroupsTaggingAPITagUntagSupportedResources and ResourceGroupsandTagEditorFullAccess AWS managed policies. These policies grant the permissions required to tag and untag all of the resource types supported by Resource Groups Tagging API, with some exceptions. This policy also grants the permissions required to retrieve all tagged, or previously tagged, resources through the Resource Groups Tagging API.

If you choose not to use the recommended AWS managed policies, ensure your manually configured policy includes all of the permissions required to tag and untag your specific resources. For example, add the sqs:TagQue permission if you have an Amazon SQS queue resource in your application. In addition to the resource-specific permissions, your policy must include the following Resource Groups Tagging API permissions:

Create a tag-sync

This section provides instructions to create a tag-sync for resources in an existing application using either myApplications in the AWS Management Console or with the AWS API.

myApplications in AWS Management Console

For instructions to bulk-onboard application resources by specifying an existing tag key-value pair at application creation, review Creating your first application in myApplications in the AWS Management Console Getting started guide.

AWS Resource Groups API

To create a tag-sync

1. Create a new tag-sync task by calling the Resource Groups StartTagSyncTask API and specifying the following parameters:

   • Group — The Amazon resource name (ARN) or name of the application group for which you want to create a tag-sync task.

   • TagKey — The tag key.

   • TagValue — The tag value.

   • RoleARN — The ARN of the role that AWS Resource Groups assumes when performing the tag-sync to apply the awsApplication tag to resources. This role must have the tagging permissions to all resources you want to include in the application. For more information, review Tag-sync required permissions.

   aws resourcegroups start-tag-sync-task --group appgroup-ARN-or-name --tagkey tag-key --tagvalue tag-value --roleArn role-ARN

   Example output:

   The output includes a TaskArn that you can later use to query the status of the tag-sync task.

   {
       "GroupArn" : "string",
       "GroupName" : "string",
       "TaskArn": "string",
       "TagKey" : "string",
       "TagValue" : "string",
       "RoleArn" : "string",
                           }

   Note

   For some accounts, an attempted StartTagSyncTask call may result in a GroupNotFound error. To resolve this error, call the AppRegistry UpdateApplication API. This call enables the application to perform tag-sync tasks.

2. Verify the status of the tag-sync task by calling the GetTagSyncTask API. Enter the TaskArn from the output of the previous StartTagSyncTask call.

   aws resourcegroups get-tag-sync-task --taskArn task-ARN

   Example output:

   {
       "GroupArn" : "string",
       "GroupName" : "string",
       "TaskArn": "string",
       "TagKey" : "string",
       "TagValue" : "string",
       "RoleArn" : "string",
       "Status" : "string",
       "ErrorMessage" : "string",
       "ManagedGroupArn": "string",
       "CreatedAt": "timestamp"
   }

(optional) To list all tag-sync tasks

To list all active tag-sync tasks, call the ListTagSyncTasks API. You can optionally include the Filters parameter with a GroupArn or GroupName to narrow your results to tasks in a specific application.

aws resourcegroups list-tag-sync-task --filters group-name

Example output:

{
    "TagSyncTasks": [
        {
            "GroupArn" : "string",
            "GroupName" : "string",
            "TaskArn": "string",
            "TagKey" : "string",
            "TagValue" : "string",
            "RoleArn" : "string",
            "Status" : "string",
            "ErrorMessage" : "string",
            "CreatedAt": "timestamp"
        }
    ],
    "NextToken": "string"
 }

To cancel a tag-sync task

To cancel a tag-sync task, call the CancelTagSyncTask API and enter the TaskArn of the tag-sync task you want to delete.

aws resourcegroups cancel-tag-sync-task --task-arn task-ARN