AWS Documentation » AWS Resource Groups » User Guide » What Is AWS Resource Groups? » Getting Started with AWS Resource Groups » Build Queries and Groups in AWS Resource Groups

Build Queries and Groups in AWS Resource Groups

In AWS Resource Groups, a query is the foundation of a group. To build a query, choose the types of resources that you want to be part of the group, and then specify the tags that are shared by the resources that you want to be members of the group. For example, if you want to create a resource group that has all of the Amazon EC2 instances and Amazon S3 buckets that you are using to run the testing stage of an application, and you have instances and buckets that are tagged this way, choose the AWS::EC2::Instance and AWS::S3::Bucket resource types from the drop-down list, and then specify the tag key Stage, with a tag value of Test.

In the AWS CLI, you build a query and create your resource group in the same command. The AWS CLI command shown in this topic creates a group.

To build a query and create a group in Resource Groups (AWS Management Console)

1. Open Resource Groups from the AWS Systems Manager console or from the top left of the AWS Management Console.

2. Choose Create a resource group.

   

3. On the Create a resource group page, choose the resource types that you want to be in your resource group. You can have a maximum of 20 resource types in a query. For the purposes of this walkthrough, choose AWS::EC2::Instance and AWS::S3::Bucket.

   

4. In the tag string boxes, specify a tag key, or a tag key and value pair, to limit the EC2 instances and S3 buckets in your account to only those that are tagged with your specified values. Choose + or press Enter when you've finished your tag. In this example, filter for resources that have a tag key of Stage. The tag value is optional, but narrows the results of the query further. To add more tags, choose +.

   Queries assign an AND operator to tags, so any resource that matches the specified resource types and all specified tags is returned by the query. If you specify multiple values in your query for a tag key, the query returns resources that match any of the values of the tag key. However, when there is more than one tag key, the query returns resources that match all tag keys, and at least one value of each specified tag key.

   

5. Choose View group resources to return the list of EC2 instances and S3 buckets in your account that match the specified tag key or keys.

6. To create a resource group based on your query, specify a name, and optionally, add a description.

   1. In the Group name box, type a name for your resource group.

      A resource group name can have a maximum of 127 characters, including letters, numbers, hyphens, dots, and underscores. The name cannot start with AWS or aws. These are reserved. A resource group name must be unique in the current region in your account.

   2. (Optional) In the Group description box, type a description of your group.

   3. (Optional) In the Group tags area, add tag key and value pairs that apply only to the resource group, not the member resources in the group.

      Group tags are useful if you plan to make this group a member of a larger group. Because specifying at least a tag key is required to create a group, be sure to add at least a tag key in Group tags to groups that you plan to nest into larger groups.

7. When you are finished, choose Create group.

To create a group in Resource Groups (AWS CLI)

In an AWS CLI command, you build a query and create a resource group based on the query in a single command.

1. In an AWS CLI session, type the following, and then press Enter, replacing the values for group name, resource types, tag keys, and tag values with your own. You can have a maximum of 20 resource types in a query. A resource group name can have a maximum of 127 characters, including letters, numbers, hyphens, dots, and underscores. The name cannot start with AWS or aws. These are reserved. A resource group name must be unique in your account. For more information about the syntax of the members of the ResourceQuery API, see ResourceQuery in the AWS Resource Groups API Reference.

   Queries assign an AND operator to tags, so any resource that matches the specified resource types and all specified tags is returned by the query. If you specify multiple values in your query for a tag key, the query returns resources that match any of the values of the tag key. However, when there is more than one tag key, the query returns resources that match all tag keys, and at least one value of each specified tag key.

   aws resource-groups create-group --name resource-group-name --resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"resource_type1\",\"resource_type2\"],\"TagFilters\":[{\"Key\":\"Key1\",\"Values\":[\"Value1\",\"Value2\"]},{\"Key\":\"Key2\",\"Values\":[\"Value1\",\"Value2\"]}]}"}'

   The following command is an example.

   aws resource-groups create-group --name my-resource-group --resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Stage\",\"Values\":[\"Test\"]}]}"}'

2. The following are returned in the response to the command.

   • A full description of the group you have created.

   • The resource query that you used to create the group.

   • The tags that are associated with the group.

After you have created a resource group, you can use the group to view insights about or perform tasks on the resources in the group.