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:

• Create an application using the existing tag key-value pair Project:Blue. For more information about bulk-onboarding 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.

• Create a tag-sync in an existing application using the Project:Blue tag.

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, create and delete resource groups, and perform tag-sync tasks. The role must also include a trust policy that allows AWS Resource Groups to 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"
    }
  ]
}

To easily and effectively apply the necessary permissions to the role, we recommend using the AWS Resource Groups ResourceGroupsTaggingAPITagUntagSupportedResources AWS managed policy. This policy grants 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. In addition to this AWS managed policy, ensure the role also includes the all of the permissions required to tag your specific resources. For example, the sqs:TagQue permission if you have an Amazon SQS queue resource.

If you choose not to use the AWS managed policy, ensure your manually configured policy includes the following permissions in addition to the service trust policy and service-specific resource permissions:

• tag:GetResources

• tag:TagResources

• tag:UntagResources

• resource-groups:GroupResources

• resource-groups:UngroupResources

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 --taskArn task-ARN