AWS::ResourceGroups::Group - Amazon CloudFormation
SyntaxPropertiesReturn valuesExamples
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).

AWS::ResourceGroups::Group

Creates a resource group with the specified name and description. You can optionally include either a resource query or a service configuration. For more information about constructing a resource query, see Build queries and groups in Amazon Resource Groups in the Amazon Resource Groups User Guide. For more information about service-linked groups and service configurations, see Service configurations for Resource Groups.

Minimum permissions

To run this command, you must have the following permissions:

  • resource-groups:CreateGroup

Syntax

To declare this entity in your Amazon CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::ResourceGroups::Group",
  "Properties" : {
      "Configuration" : [ ConfigurationItem, ... ],
      "Description" : String,
      "Name" : String,
      "ResourceQuery" : ResourceQuery,
      "Resources" : [ String, ... ],
      "Tags" : [ Tag, ... ]
    }
}

YAML

Type: AWS::ResourceGroups::Group
Properties:
  Configuration: 
    - ConfigurationItem
  Description: String
  Name: String
  ResourceQuery: 
    ResourceQuery
  Resources: 
    - String
  Tags: 
    - Tag

Properties

Configuration

The service configuration currently associated with the resource group and in effect for the members of the resource group. A Configuration consists of one or more ConfigurationItem entries. For information about service configurations for resource groups and how to construct them, see Service configurations for resource groups in the Amazon Resource Groups User Guide.

Note

You can include either a Configuration or a ResourceQuery, but not both.

Required: Conditional

Type: Array of ConfigurationItem

Update requires: No interruption

Description

The description of the resource group.

Required: No

Type: String

Maximum: 512

Update requires: No interruption

Name

The name of a resource group. The name must be unique within the Amazon Region in which you create the resource. To create multiple resource groups based on the same CloudFormation stack, you must generate unique names for each.

Required: Yes

Type: String

Maximum: 128

Update requires: Replacement

ResourceQuery

The resource query structure that is used to dynamically determine which Amazon resources are members of the associated resource group. For more information about queries and how to construct them, see Build queries and groups in Amazon Resource Groups in the Amazon Resource Groups User Guide

Note

  • You can include either a ResourceQuery or a Configuration, but not both.

  • You can specify the group's membership either by using a ResourceQuery or by using a list of Resources, but not both.

Required: Conditional

Type: ResourceQuery

Update requires: No interruption

Resources

A list of the Amazon Resource Names (ARNs) of Amazon resources that you want to add to the specified group.

Note

  • You can specify the group membership either by using a list of Resources or by using a ResourceQuery, but not both.

  • You can include a Resources property only if you also specify a Configuration property.

Required: Conditional

Type: Array of String

Update requires: No interruption

Tags

The tag key and value pairs that are attached to the resource group.

Required: No

Type: Array of Tag

Update requires: No interruption

Return values

Ref

The name of the new resource group.

Fn::GetAtt

Arn

The ARN of the new resource group.

Examples

The following examples show both the JSON and YAML templates that you can use to create resource groups with the specified characteristics.

Creating a CloudFormation stack-based resource group using defaults

This example creates a CloudFormation stack-based resource group using defaults. It includes all supported resource types and uses the same StackIdentifier as the CloudFormation stack that defines the group.

JSON

{
    "ResourceGroup": { 
        "Type": "AWS::ResourceGroups::Group",
        "Properties": {
            "Name": "MyResourceGroup",
            "Description": "A basic, empty resource group that is created by CFN",
        }
    } 
}

YAML

ResourceGroup:
  Type: "AWS::ResourceGroups::Group" 
  Properties:
    Name: "MyMinimalResourceGroup"
    Description: "A basic, empty resource group that is created by CFN"

Creating a CloudFormation stack-based resource group with specific resources

This example creates a CloudFormation stack-based resource group that's similar to the group shown in the previous example. The difference is that it can include only resources of the specified types: EC2 instances and DynamoDB tables.

JSON

{
    "CloudFormationStackGroupForSelectedResourceTypes": {
        "Type": "AWS::ResourceGroups::Group",
        "Properties": {
            "Name": "MyCloudFormationResourceGroup-Filters",
            "Description": "A basic resource group that can hold only EC2 instances or DynamoDB tables", 
            "ResourceQuery": {
                "Query": {
                    "ResourceTypeFilters": [
                        "AWS::EC2::Instance",
                        "AWS::DynamoDB::Table" 
                    ] 
                } 
            }
        }
    }
}

YAML

CloudFormationStackGroupForSelectedResourceTypes:
  Type: "AWS::ResourceGroups::Group" 
  Properties: 
    Name: "MyCloudFormationResourceGroup-Filters"
    Description: "A basic resource group that can hold only EC2 instances or DynamoDB tables"
    ResourceQuery: 
      Query: 
        ResourceTypeFilters: 
          - "AWS::EC2::Instance" 
          - "AWS::DynamoDB::Table"

Creating a CloudFormation stack-based resource group based on another stack

This example creates a resource group that's built from another stack. The StackIdentifier value specifies that resources in the stack with the ARN arn:aws-cn:cloudformation:us-east-1:123456789012:stack/stack-name/9b6f8604-4a39-490c-870b-44b0ebdd38b9 are included in the group. The group itself (not its individual member resources) is tagged with Env=Prod.

JSON

{
    "CloudFormationStackGroupForAnotherStack": {
        "Type": "AWS::ResourceGroups::Group",
        "Properties": {
            "Name": "MyCloudFormationResourceGroupForAnotherStack",
            "Description": "A resource group that is based on another CFN stack",
            "ResourceQuery": { 
                "Type": "CLOUDFORMATION_STACK_1_0",
                "Query": {
                    "ResourceTypeFilters": [
                        "AWS::AllSupported" 
                    ],
                    "StackIdentifier": "arn:aws-cn:cloudformation:us-east-1:123456789012:stack/stack-name/9b6f8604-4a39-490c-870b-44b0ebdd38b9"
                }
            },
            "Tags": [
                {
                    "Key": "Env",
                    "Value": "Prod" 
                }
            ]
        }
    }
}

YAML

CloudFormationStackGroupForAnotherStack:
  Type: "AWS::ResourceGroups::Group" 
  Properties: 
    Name: "MyCloudFormationResourceGroupForAnotherStack" 
    Description: "A group that is based on CFN another stack" 
    ResourceQuery: 
      Type: "CLOUDFORMATION_STACK_1_0" 
      Query: 
        ResourceTypeFilters:
          - "AWS::AllSupported" 
        StackIdentifier: "arn:aws-cn:cloudformation:us-east-1:123456789012:stack/stack-name/9b6f8604-4a39-490c-870b-44b0ebdd38b9"
    Tags: 
      -
        Key: "Env" 
        Value: "Prod"

Creating a tag-based resource group

This example shows how to create a resource group whose membership is based on a tag query. Any resources that have tags that match the query, in this case the key Usage and the value Integration Tests, are members of this group.

JSON

{
    "TagBasedGroup": {
        "Type": "AWS::ResourceGroups::Group",
        "Properties": {
            "Name": "MyTagBasedResourceGroup",
            "Description": "A group that is based on a tag query",
            "ResourceQuery": {
                "Type": "TAG_FILTERS_1_0",
                "Query": {
                    "ResourceTypeFilters": [
                        "AWS::AllSupported" 
                    ],
                    "TagFilters": [
                        {
                            "Key": "Usage",
                            "Values": [
                                "Integration Tests" 
                            ]
                        }
                    ]
                }
            }
        }
    }
}

YAML

TagBasedGroup:
  Type: "AWS::ResourceGroups::Group"
  Properties:
    Name: "MyTagBasedResourceGroup"
    Description: "A group that is based on a tag query"
    ResourceQuery:
      Type:
        "TAG_FILTERS_1_0" 
      Query:
        ResourceTypeFilters: 
          - "AWS::AllSupported" 
        TagFilters:
          - 
            Key: "Usage" 
            Values: 
              - "Integration Tests"

Creating a resource group for EC2 capacity reservations

This example creates a capacity reservations resource group by specifying a configuration and limiting the allowed resource types. This group initially has no members.

JSON

{
   "CapacityReservationsGroupWithoutResources": {
      "Type": "AWS::ResourceGroups::Group",
      "Properties": {
         "Name": "MyCapacityReservationsGroup",
         "Description": "A resource group for EC2 capacity reservations",
         "Configuration": [
            {
               "Type": "AWS::EC2::CapacityReservationPool",
               "Parameters": []
            },
            {
               "Type": "AWS::ResourceGroups::Generic",
               "Parameters": [
                  {
                     "Name": "allowed-resource-types",
                     "Values": [
                        "AWS::EC2::CapacityReservation"
                     ]
                  }
               ]
            }
         ]
      }
   }
}

YAML

CapacityReservationsGroupWithoutResources:
  Type: "AWS::ResourceGroups::Group"
  Properties:
    Name: "MyCapacityReservationsGroup"
    Description: "A resource group for EC2 capacity reservations"
    Configuration:
    - Type: "AWS::EC2::CapacityReservationPool"
      Parameters: []
    - Type: "AWS::ResourceGroups::Generic"
      Parameters:
      - Name: "allowed-resource-types"
        Values:
          - "AWS::EC2::CapacityReservation"

Creating a resource group for EC2 capacity reservations with initial members

This example creates a capacity reservations resource group identical to the previous example, except this one includes two initial capacity reservations as specified in the Resources property.

JSON

{
   "CapacityReservationsGroupWithResources": {
      "Type": "AWS::ResourceGroups::Group",
      "Properties": {
         "Name": "MyCapacityReservationsGroup",
         "Description": "A resource group for EC2 capacity reservations",
         "Configuration": [
            {
               "Type": "AWS::EC2::CapacityReservationPool",
               "Parameters": []
            },
            {
               "Type": "AWS::ResourceGroups::Generic",
               "Parameters": [
                  {
                     "Name": "allowed-resource-types",
                     "Values": [
                        "AWS::EC2::CapacityReservation"
                     ]
                  }
               ]
            }
         ],
         "Resources": [
            "arn:aws-cn:ec2:us-east-1:123456789012:capacity-reservation/cr-0d4953834cd1a96a3",
            "arn:aws-cn:ec2:us-east-1:123456789012:capacity-reservation/cr-0069a2275c16b7333"
         ]
      }
   }
}

YAML

CapacityReservationsGroupWithResources:
  Type: "AWS::ResourceGroups::Group"
  Properties:
    Name: "MyCapacityReservationsGroup"
    Description: "A resource group for EC2 capacity reservations"
    Configuration:
    - Type: "AWS::EC2::CapacityReservationPool"
      Parameters: []
    - Type: "AWS::ResourceGroups::Generic"
      Parameters:
      - Name: "allowed-resource-types"
        Values:
          - "AWS::EC2::CapacityReservation"
    Resources:
      - "arn:aws-cn:ec2:us-east-1:123456789012:capacity-reservation/cr-0d4953834cd1a96a3"
      - "arn:aws-cn:ec2:us-east-1:123456789012:capacity-reservation/cr-0069a2275c16b7333"

Creating an EC2 hosts resource group

This example creates a host resource group. Instances in the group are automatically configured to accept any host based license configuration, to allow only the c5 host family, to not auto-release hosts, and to be delete protected. The group initially has no members.

JSON

{
  "HostResourceGroup": {
    "Type": "AWS::ResourceGroups::Group",
    "Properties": {
      "Name": "MyHostResourceGroup",
      "Description": "A resource group for EC2 dedicated hosts",
      "Configuration": [
        {
          "Type": "AWS::EC2::HostManagement",
          "Parameters": [
            {
              "Name": "any-host-based-license-configuration",
              "Values": [
                "true"
              ]
            },
            {
              "Name": "allowed-host-families",
              "Values": [
                "c5"
              ]
            },
            {
              "Name": "auto-release-host",
              "Values": [
                "false"
              ]
            }
          ]
        },
        {
          "Type": "AWS::ResourceGroups::Generic",
          "Parameters": [
            {
              "Name": "allowed-resource-types",
              "Values": [
                "AWS::EC2::Host"
              ]
            },
            {
              "Name": "deletion-protection",
              "Values": [
                "UNLESS_EMPTY"
              ]
            }
          ]
        }
      ]
    }
  }
}

YAML

HostResourceGroup:
  Type: "AWS::ResourceGroups::Group"
  Properties:
    Name: "MyHostResourceGroup"
    Description: "A resource group for EC2 dedicated hosts"
    Configuration:
      - Type: "AWS::EC2::HostManagement"
        Parameters:
          - Name: "any-host-based-license-configuration"
            Values:
              - "true"
          - Name: "allowed-host-families"
            Values:
              - "c5"
          - Name: "auto-release-host"
            Values:
              - "false"
      - Type: "AWS::ResourceGroups::Generic"
        Parameters:
          - Name: "allowed-resource-types"
            Values:
              - "AWS::EC2::Host"
          - Name: "deletion-protection"
            Values:
              - "UNLESS_EMPTY"

Creating an EC2 hosts resource group with some initial members

This example creates an EC2 host resource group that is configured to work with a specific license configuration. The group initially contains the two hosts specified by the Resources property

JSON

{
  "HostResourceGroupWithResources": {
    "Type": "AWS::ResourceGroups::Group",
    "Properties": {
      "Name": "MyHostResourceGroup",
      "Description": "A resource group for EC2 dedicated hosts",
      "Configuration": [
        {
          "Type": "AWS::EC2::HostManagement",
          "Parameters": [
            {
              "Name": "allowed-resource-types",
              "Values": [
                "AWS::EC2::Host"
              ]
            },
            {
              "Name": "deletion-protection",
              "Values": [
                "UNLESS_EMPTY"
              ]
            }
          ]
        }
      ],
      "Resources": [
        "arn:aws-cn:ec2:us-east-1:123456789012:dedicated-host/h-0375ef7462b26b11f",
        "arn:aws-cn:ec2:us-east-1:123456789012:dedicated-host/h-0501ab6812c719123"
      ]
    }
  }
}

YAML

HostResourceGroupWithResources:
  Type: "AWS::ResourceGroups::Group"
  Properties:
    Name: "MyHostResourceGroup"
    Description: "A resource group for EC2 dedicated hosts"
    Configuration:
      - Type: "AWS::EC2::HostManagement"
        Parameters:
          - Name: "allowed-host-based-license-configurations"
            Values:
              - "arn:aws-cn:license-manager:us-east-1:123456789012:license-configuration:lic-42bc5628e8edcee52ed797d5bebf0879"
        Parameters:
          - Name: "allowed-resource-types"
            Values:
              - "AWS::EC2::Host"
          - Name: "deletion-protection"
            Values:
              - "UNLESS_EMPTY"
    Resources:
      - "arn:aws-cn:ec2:us-east-1:123456789012:dedicated-host/h-0375ef7462b26b11f"
      - "arn:aws-cn:ec2:us-east-1:123456789012:dedicated-host/h-0501ab6812c719123"