Service configurations for resource groups - AWS Resource Groups

Service configurations for resource groups

Resource groups enable you to manage collections of your AWS resources as a unit. Some AWS 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 AWS services.

How to access the service configuration attached to a resource group

Services that support this feature typically set the configuration for you when you use the tools provided by that service. You can also interact with the configuration in Resource Groups by using the following API operations in the AWS SDKs or their AWS 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 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.

[ { "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 control the requirements for the resource group itself, rather than configuring the behavior of a specific resource type for an AWS service.

The following parameters are valid for this type.

  • allowed-resource-types

    Use this parameter to specify that the group can consist of resources of only the specified type or types.

    Data type of values: String

    Permitted values:

    • AWS::EC2::Host – this parameter and this value is required when the service configuration contains a configuration item of type AWS::EC2::HostManagement.

    • AWS::EC2::CapacityReservation – this parameter and this value is required when the service configuration contains a configuration item of type AWS::EC2::CapacityReservationPool.

    Required: Conditional. See the previous entry for Permitted values.

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

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

    Use this parameter to specify that the resource group can't be deleted unless it contains no hosts. 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" ] (must be upper case).

    Required: Conditional. This parameter is required when the specified configuration type is AWS::EC2::HostManagement.

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

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

AWS::EC2::CapacityReservationPool

This configuration type specifies that the group represents a common pool of capacity provided by the group's members. The members are required to be Amazon EC2 capacity reservations. When you launch an Amazon EC2 instance with this group specified as the value for the capacity reservation parameter, then the instance uses the available reserved capacity in the group. If no capacity is available in the group, 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 for Linux Instances.

If you set a group configuration item with this type, then you must also specify a group configuration item with the AWS::ResourceGroups::Generic type, with a parameter of allowed-resource-types and a single value of AWS::EC2::CapacityReservation. This ensures that only capacity reservations can be members of the group.

The AWS::EC2::CapacityReservation configuration item 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 AWS License Manager that are enforced for the group's members. For more information, see Host resource groups in AWS License Manager.

If you set a group configuration item with this type, then you must also specify group 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 this type.

  • auto-allocate-host

    This parameter specifies whether instances that you launch 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 for Linux Instances.

    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 for Linux Instances.

    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 the instance type families that the instances that are members of this group are allowed to use.

    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 the instances use 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 Names (ARNs) 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: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" ] } ] } }
  • 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" ] } ] } }