Service configurations for resource groups - Amazon Resource Groups
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).

Service configurations for resource groups

Resource groups enable you to manage collections of your Amazon resources as a unit. Some Amazon services support this by performing requested operations on all members of the group. Such services can store the settings to be applied to group members as a configuration in the form of a JSON data structure that is attached to the group.

This topic describes the available configuration settings for supported Amazon services.

How to access the service configuration attached to a resource group

Services that support service-linked groups typically set the configuration for you when you use the tools provided by that service, such as that service's management console or its Amazon CLI and Amazon SDK operations. Some services fully manage their service-linked groups and you can't modify them in any way except as allowed by the console or commands provided by the owning Amazon service. However, in some cases, you can interact with the service configuration by using the following API operations in the Amazon SDKs or their Amazon CLI equivalents:

  • You can attach your own configuration to a group when you create the group by using the CreateGroup operation.

  • You can modify the current configuration attached to a group by using the PutGroupConfiguration operation.

  • You can view the current configuration of a resource group by calling the GetGroupConfiguration operation.

JSON syntax of a service configuration

A resource group can contain a configuration that defines service-specific settings that apply to the resources that are members of that group.

A configuration is expressed as a JSON object. At the top-most level, a configuration is an array of group configuration items. Each group configuration item contains two elements: a Type for the configuration and a set of Parameters defined by that type. Each parameter contains a Name and an array of one or more Values. The following example with placeholders shows the basic syntax for a configuration for a single sample resource type. This example shows a type with two parameters, and each parameter with two values. The actual valid types, parameters, and values are discussed in the next section.

{ "Configuration": [ { "Type": "configuration-type", "Parameters": [ { "Name": "parameter1-name", "Values": [ "value1", "value2" ] }, { "Name": "parameter2-name", "Values": [ "value3", "value4" ] } ] } ] }

Supported configuration types and parameters

Resource Groups supports using the following configuration types. Each configuration type has a set of parameters that are valid for that type.

AWS::ResourceGroups::Generic

This configuration type specifies settings that enforce membership requirements on the resource group, rather than configuring the behavior of a specific resource type for an Amazon service. This configuration type is automatically added by those service-linked groups that need it, such as the AWS::EC2::CapacityReservationPool and AWS::EC2::HostManagment types.

The following Parameters are valid for the AWS::ResourceGroups::Generic service-linked group Type.

  • allowed-resource-types

    This parameter specifies that the resource group can consist of resources of only the specified type or types.

    Data type of values: String

    Permitted values:

    • AWS::EC2::Host – A Configuration with this parameter and value is required when the service configuration also contains a Configuration of type AWS::EC2::HostManagement. This ensures that the HostManagement group can contain only Amazon EC2 dedicated hosts.

    • AWS::EC2::CapacityReservation – A Configuration with this parameter and value is required when the service configuration also contains a Configuration item of type AWS::EC2::CapacityReservationPool. This ensures that a CapacityReservation group can contain only Amazon EC2 capacity reservation capacity.

    Required: Conditional, based on other Configuration elements that are attached to the resource group. See the previous entry for Permitted values.

    The following example restricts group members to only Amazon EC2 host instances.

    { "Configuration": [ { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": ["AWS::EC2::Host"] } ] } ] }
  • deletion-protection

    This parameter specifies that the resource group can't be deleted unless it contains no members. For more information, see Delete a host resource group in the License Manager User Guide

    Data type of values: Array of string

    Permitted values: The only permitted value is [ "UNLESS_EMPTY" ] (the value must be upper case).

    Required: Conditional, based on other Configuration elements that are attached to the resource group. This parameter is required only when the resource group also has another Configuration element with the Type of AWS::EC2::HostManagement.

    The following example enables delete protection for the group unless the group has no members.

    { "Configuration": [ { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "deletion-protection", "Values": [ "UNLESS_EMPTY" ] } ] } ] }

AWS::AppRegistry::Application

This Configuration type specifies that the resource group represents an application created by Amazon Service Catalog AppRegistry.

Resource groups of this type are fully managed by the AppRegistry service, and can't be created, updated, or deleted by users other than by using the tools provided by AppRegistry.

Note

Because resource groups of this type are automatically created and maintained by Amazon and not managed by the user, these resource groups do not count against your quota limit for the maximum number of resource groups that you can create in your Amazon Web Services account.

For more information, see Using AppRegistry in the Service Catalog User Guide.

When AppRegistry creates a service-linked resource group of this type, it also automatically creates a separate, additional Amazon CloudFormation service-linked group for each Amazon CloudFormation stack associated with the application.

AppRegistry automatically names the service-linked groups of this type that its creates with the prefix AWS_AppRegistry_Application- followed by the name of the application: AWS_AppRegistry_Application-MyAppName

The following parameters are supported for the AWS::AppRegistry::Application service-linked group type.

  • Name

    This parameter specifies the friendly name of the application that was assigned by the user when it was created in AppRegistry.

    Data type of values: String

    Permitted values: any text string permitted by the AppRegistry service for an application name.

    Required: Yes

  • Arn

    This parameter specifies the Amazon Resource Name (ARN) path of the application assigned by AppRegistry.

    Data type of values: String

    Permitted values: a valid ARN.

    Required: Yes

Note

To change any of these elements, you must modify the application using the AppRegistry console or that service's Amazon SDK and Amazon CLI operations.

This application resource group automatically includes as group members the resource groups created for the Amazon CloudFormation stacks that are associated with the AppRegistry application. You can use the ListGroupResources operation to see those child groups.

The following example shows what the configuration section of a AWS::AppRegistry::Application service-linked group looks like.

{ "Configuration": [ { "Type": "AWS::AppRegistry::Application", "Parameters":[ { "Name": "Name", "Values": [ "MyApplication" ] }, { "Name": "Arn", "Values": [ "arn:aws-cn:servicecatalog:us-east-1:123456789012:/applications/<application-id>" ] } ] } ] }

AWS::CloudFormation::Stack

This Configuration type specifies that the group represents an Amazon CloudFormation stack and its members are the Amazon resources created by that stack.

Resource groups of this type are automatically created for you when you associate a Amazon CloudFormation stack with the AppRegistry service. You can't create, update, or delete these groups except by using the tools provided by AppRegistry.

AppRegistry automatically names the service-linked groups of this type that its creates with the prefix AWS_CloudFormation_Stack- followed by the name of the stack: AWS_CloudFormation_Stack-MyStackName

Note

Because resource groups of this type are automatically created and maintained by Amazon and not managed by the user, these resource groups do not count against your quota limit for the maximum number of resource groups that you can create in your Amazon Web Services account.

For more information, see Using AppRegistry in the Service Catalog User Guide.

AppRegistry automatically creates a service-linked resource group of this type for every Amazon CloudFormation stack that you associate with the AppRegistry application. These resource groups become child members of the parent resource group for the AppRegistry application.

The members of this Amazon CloudFormation resource group are the Amazon resources created as part of the stack.

The following parameters are supported for the AWS::CloudFormation::Stack service-linked group type.

  • Name

    This parameter specifies the friendly name of the Amazon CloudFormation stack assigned by the user when the stack was created.

    Data type of values: String

    Permitted values: any text string permitted by the Amazon CloudFormation service for a stack name.

    Required: Yes

  • Arn

    This parameter specifies the Amazon Resource Name (ARN) path of the Amazon CloudFormation stack attached to the application in AppRegistry.

    Data type of values: String

    Permitted values: a valid ARN.

    Required: Yes

Note

To change any of these elements, you must modify the application using the AppRegistry console or equivalent Amazon SDK and Amazon CLI operations.

The following example shows what the configuration section of an AWS::CloudFormation::Stack service-linked group looks like.

{ "Configuration": [ { "Type": "AWS::CloudFormation::Stack", "Parameters":[ { "Name": "Name", "Values": [ "MyStack" ] }, { "Name": "Arn", "Values": [ "arn:aws-cn:cloudformation:us-east-1:123456789012:stack/MyStack/<stack-id>" ] } ] } ] }

AWS::EC2::CapacityReservationPool

This Configuration type specifies that the resource group represents a common pool of capacity provided by the group's members. The members of this resource group are required to be Amazon EC2 capacity reservations. A resource group can include both capacity reservations that you own in your account and capacity reservations that are shared with you from other accounts by using Amazon Resource Access Manager. This lets you launch an Amazon EC2 instance using this resource group as the value for the capacity reservation parameter. When you do this, the instance uses the available reserved capacity in the group. If resource group has no available capacity, the instance launches as a stand alone on-demand instance outside of the pool. For more information, see Working with Capacity Reservation groups in the Amazon EC2 User Guide.

If you configure a service-linked resource group with a Configuration item of this type, then you must also specify separate Configuration items with the following values:

  • An AWS::ResourceGroups::Generic type with one parameter:

    • The parameter allowed-resource-types and a single value of AWS::EC2::CapacityReservation. This ensures that only Amazon EC2 capacity reservations can be members of the resource group.

The AWS::EC2::CapacityReservationPool item in a group configuration doesn't support any parameters.

The following example shows what the Configuration section of such a group looks like.

{ "Configuration": [ { "Type": "AWS::EC2::CapacityReservationPool" }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": [ "AWS::EC2::CapacityReservation" ] } ] } ] }

AWS::EC2::HostManagement

This identifier specifies settings for Amazon EC2 host management and Amazon License Manager that are enforced for the group's members. For more information, see Host resource groups in Amazon License Manager.

If you configure a service-linked resource group with a Configuration item of this type, then you must also specify separate Configuration items with the following values:

  • An AWS::ResourceGroups::Generic type, with a parameter of allowed-resource-types and a single value of AWS::EC2::Host. This ensures that only Amazon EC2 dedicated hosts can be members of the group.

  • An AWS::ResourceGroups::Generic type, with a parameter of deletion-protection and a single value of UNLESS_EMPTY. This ensures that the group can't be deleted unless the group is empty.

The following parameters are supported for the AWS::EC2::HostManagement service-linked group type.

  • auto-allocate-host

    This parameter specifies whether instances are launched onto a specific dedicated host, or onto any available host that has a matching configuration. For more information, see Understanding auto-placement and affinity in the Amazon EC2 User Guide.

    Data type of values: Boolean

    Permitted values: "true" or "false" (must be lower case).

    Required: No

    { "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "Name": "auto-allocate-host", "Values": [ "true" ] } ] }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": [ "AWS::EC2::Host" ] }, { "Name": "deletion-protection", "Values": [ "UNLESS_EMPTY" ] } ] } ] }
  • auto-release-host

    This parameter specifies whether a dedicated host in the group is automatically released after its last running instance is terminated. For more information, see Releasing Dedicated Hosts in the Amazon EC2 User Guide.

    Data type of values: Boolean

    Permitted values: "true" or "false" (must be lower case).

    Required: No

    { "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "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" ] } ] } ] }
  • allowed-host-families

    This parameter specifies which instance type families can be used by instances that are members of this group.

    Data type of values: An array of String.

    Permitted values: Each must be a valid Amazon EC2 instance type family identifier, such as C4, M5, P3dn, or R5d.

    Required: No

    The following example configuration item specifies that launched instances can be only members of the C5 or M5 instance type families.

    { "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "Name": "allowed-host-families", "Values": ["c5", "m5"] } ] }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": ["AWS::EC2::Host"] }, { "Name": "deletion-protection", "Values": ["UNLESS_EMPTY"] } ] } ] }
  • allowed-host-based-license-configurations

    This parameter specifies the Amazon Resource Name (ARN) paths of one or more core/socket based license configurations that you want applied to members of the group.

    Data type of values: An array of ARNs.

    Permitted values: Each must be a valid License Manager configuration ARN.

    Required: Conditional. You must specify either this parameter or any-host-based-license-configuration, but not both. They are mutually exclusive.

    The following example configuration item specifies that group members can use the two specified License Manager configurations.

    { "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "Name": "allowed-host-based-license-configurations", "Values": [ "arn:aws-cn:license-manager:us-west-2:123456789012:license-configuration:lic-6eb6586f508a786a2ba41EXAMPLE1111", "arn:aws-cn:license-manager:us-west-2:123456789012:license-configuration:lic-8a786a26f50ba416eb658EXAMPLE2222" ] } ] }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": [ "AWS::EC2::Host" ] }, { "Name": "deletion-protection", "Values": [ "UNLESS_EMPTY" ] } ] } ] }
  • any-host-based-license-configuration

    This parameter specifies that you do not want to associate a specific license configuration to your group. In this case, all core/socket based license configurations are available to your members of your host resource group. Use this setting if you have an unlimited number of licenses and want to optimize for host utilization.

    Data type of values: Boolean

    Permitted values: "true" or "false" (must be lower case).

    Required: Conditional. You must specify either this parameter or allowed-host-based-license-configurations, but not both. They are mutually exclusive.

    The following example configuration item specifies that group members can use any core/socket based license configuration.

    { "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "Name": "any-host-based-license-configuration", "Values": ["true"] } ] }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": ["AWS::EC2::Host"] }, { "Name": "deletion-protection", "Values": ["UNLESS_EMPTY"] } ] } ] }

The following example illustrates how to include all of the host management settings together in a single configuration.

{ "Configuration": [ { "Type": "AWS::EC2::HostManagement", "Parameters": [ { "Name": "auto-allocate-host", "Values": ["true"] }, { "Name": "auto-release-host", "Values": ["false"] }, { "Name": "allowed-host-families", "Values": ["c5", "m5"] }, { "Name": "allowed-host-based-license-configurations", "Values": [ "arn:aws:license-manager:us-west-2:123456789012:license-configuration:lic-6eb6586f508a786a2ba41EXAMPLE1111", "arn:aws:license-manager:us-west-2:123456789012:license-configuration:lic-8a786a26f50ba416eb658EXAMPLE2222" ] } ] }, { "Type": "AWS::ResourceGroups::Generic", "Parameters": [ { "Name": "allowed-resource-types", "Values": ["AWS::EC2::Host"] }, { "Name": "deletion-protection", "Values": ["UNLESS_EMPTY"] } ] } ] }

AWS::NetworkFirewall::RuleGroup

This identifier specifies settings for Amazon Network Firewall rule groups that are enforced for the group's members. Firewall administrators can specify the ARN of a resource group of this type to automatically resolve the IP addresses of the group's members for a firewall rule instead of having to list each address manually. For more information, see Using tag-based resource groups in Amazon Network Firewall.

You can create resource groups of this configuration type by using the Network Firewall console or by running a Amazon CLI command or Amazon SDK operation.

Resource groups of this configuration type have the following restrictions:

  • The group's members consist of only resources of types supported by Network Firewall.

  • The group must contain a tag-based query to manage the group's membership; any resources of supported types with tags that match the query are automatically members of the group.

  • There are no Parameters supported for this configuration type.

  • To delete a resource group of this configuration type, it can't be referenced by any Network Firewall rule group.

The following example illustrates the Configuration and ResourceQuery sections for a group of this type.

{ "Configuration": [ { "Type": "AWS::NetworkFirewall::RuleGroup", "Parameters": [] } ], "ResourceQuery": { "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"environment\",\"Values\":[\"production\"]}]}", "Type": "TAG_FILTERS_1_0" } }

The following example Amazon CLI command creates a resource group with the previous configuration and query.

$ aws resource-groups create-group \ --name test-group \ --resource-query '{"Type": "TAG_FILTERS_1_0", "Query": "{\"ResourceTypeFilters\": [\"AWS::EC2::Instance\"], \"TagFilters\": [{\"Key\": \"environment\", \"Values\": [\"production\"]}]}"}' \ --configuration '[{"Type": "AWS::NetworkFirewall::RuleGroup", "Parameters": []}]' { "Group":{ "GroupArn":"arn:aws:resource-groups:us-west-2:123456789012:group/test-group", "Name":"test-group", "OwnerId":"123456789012" }, "Configuration": [ { "Type": "AWS::NetworkFirewall::RuleGroup", "Parameters": [] } ], "ResourceQuery": { "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"environment\",\"Values\":[\"production\"]}]}", "Type": "TAG_FILTERS_1_0" } }