AWS Resource Groups
User Guide

Finding Resources in AWS Resource Groups

You can use Resource Groups to search or query for resources in the current region within your account, and optionally create a group of resources that are returned as search results. You can also run the AWS CLI command search-resources to find resources of specific types that have specific tags. To search for resources and create a group in a single AWS CLI command, run create-group.

Find Resources Using the AWS Management Console

The Find resources page lets you build queries by selecting resource types, and specifying tags that are shared by resources of those types.

To build a query of resources in Resource Groups in the AWS Management Console

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

  2. In the navigation pane, choose Find resources.

    
                        Find resources page.
  3. In the Resource query area, choose resource types in the Select resource types drop-down list. You can have a maximum of 20 resource types in a query. For this walkthrough, choose AWS::EC2::Instance and AWS::S3::Bucket.

    
                        Find resources page with EC2 instances and S3
                            buckets selected as resource types.
  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 the current region 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.

    
                        Query with tag key specified.
  5. Choose View query results to return the list of EC2 instances and S3 buckets in the current region that match the specified tag key or keys.

    
                        Results of query.

    If you only wanted to find resources by building a query, you have finished the procedure. To create a resource group based on your query, choose Save query as group, and go on to the next step.

  6. On the Create query-based group page, in the Group details area, specify a group 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 128 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.

  7. (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.

  8. To create your group, choose Create group.

Find Resources Using the AWS CLI

The procedure in this section builds queries by using the search-resources command to find resources of specific types that have specific tags. To search for resources and create a group in a single AWS CLI command, run create-group. For more information about how to build a query and create a group in a single command, see Build Queries and Groups in AWS Resource Groups.

Note

The SearchResources API currently does not support finding untagged resources. You can use it only to find resources within a single region that are already tagged with at least one tag key.

To build a query and find resources in Resource Groups (AWS CLI)

  1. In an AWS CLI session, type the following, and then press Enter, replacing the values for resource query type, resource type filters, tag keys, and tag values with your own. The Type attribute of --resource-query currently has one valid value, TAG_FILTERS_1_0. Both ResourceTypeFilters and TagFilters are required in the Query attribute. To search for all resource types that have a specific tag, specify [\"AWS::AllSupported\"] as the value of ResourceTypeFilters. You can have a maximum of 20 resource types in a query. At least one tag key is required, but specifying tag values is optional.

    aws resource-groups search-resources --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 finds all EC2 instances in the current region within your account that have a tag key of Stage and a value of Test.

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

    The following command is an example that does not filter for any specific resource types (all resource types are included in the query), and that specifies only a tag key of Stage, but no tag values.

    aws resource-groups search-resources --resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"TagFilters\":[{\"Key\":\"Stage\"}]}"}'
  2. The following are returned in the response to the command.

    • The ARNs of each resource that the query returns.

    • The type of each resource that the query returns.

    The results of the search-resources command look similar to the following example.

    HTTP/1.1 200 Content-type: application/json { "NextToken": "NextToken value, if provided to paginate results", "ResourceIdentifiers": [ { "ResourceArn": "arn:aws:ec2:us-west-2:123456789012:instance/*", "ResourceType": "AWS::EC2::Instance" }, { "ResourceArn": "arn:aws:ec2:us-west-2:123456789000:instance/*", "ResourceType": "AWS::EC2::Instance" } ] }