Work with Capacity Reservation groups
You can use Amazon Resource Groups to create logical collections of Capacity Reservations, called resource groups. A resource group is a logical grouping of Amazon resources that are all in the same Amazon Region. For more information about resource groups, see What are resource groups? in the Amazon Resource Groups User Guide.
You can include Capacity Reservations that you own in your account, and Capacity Reservations that are shared with you by other Amazon accounts in a single resource group. You can also include Capacity Reservations that have different attributes (instance type, platform, and Availability Zone) in a single resource group.
When you create resource groups for Capacity Reservations, you can target instances to a group of Capacity Reservations instead of an individual Capacity Reservation. Instances that target a group of Capacity Reservations match with any Capacity Reservation in the group that has matching attributes (instance type, platform, and Availability Zone) and available capacity. If the group does not have a Capacity Reservation with matching attributes and available capacity, the instances run using On-Demand capacity. If a matching Capacity Reservation is added to the targeted group at a later stage, the instance is automatically matched with and moved into its reserved capacity.
To prevent unintended use of Capacity Reservations in a group, configure the Capacity Reservations in the group to accept
only instances that explicitly target the capacity reservation. To do this, set
Instance eligibility to targeted (old console)
or Only instances that specify this reservation (new console) when
creating the Capacity Reservation using the Amazon EC2 console. When using the Amazon CLI, specify
--instance-match-criteria targeted
when creating the Capacity Reservation. Doing this ensures
that only instances that explicitly target the group, or a Capacity Reservation in the group, can run in
the group.
If a Capacity Reservation in a group is canceled or expires while it has running instances, the instances are automatically moved to another Capacity Reservation in the group that has matching attributes and available capacity. If there are no remaining Capacity Reservations in the group that have matching attributes and available capacity, the instances run in On-Demand capacity. If a matching Capacity Reservation is added to the targeted group at a later stage, the instance is automatically moved into its reserved capacity.
Topics
Create a Capacity Reservation group
To create a group for Capacity Reservations
Use the create-group Amazon CLI command. For name
, provide a descriptive name for the group, and for configuration
, specify two Type
request parameters:
-
AWS::EC2::CapacityReservationPool
to ensure that the resource group can be targeted for instance launches -
AWS::ResourceGroups::Generic
withallowed-resource-types
set toAWS::EC2::CapacityReservation
to ensure that the resource group accepts Capacity Reservations only
For example, the following command creates a group named MyCRGroup
.
C:\>
aws resource-groups create-group --nameMyCRGroup
--configuration '{"Type":"AWS::EC2::CapacityReservationPool"}' '{"Type":"AWS::ResourceGroups::Generic", "Parameters": [{"Name": "allowed-resource-types", "Values": ["AWS::EC2::CapacityReservation"]}]}'
The following shows example output.
{
"GroupConfiguration": {
"Status": "UPDATE_COMPLETE",
"Configuration": [
{
"Type": "AWS::EC2::CapacityReservationPool"
},
{
"Type": "AWS::ResourceGroups::Generic",
"Parameters": [
{
"Values": [
"AWS::EC2::CapacityReservation"
],
"Name": "allowed-resource-types"
}
]
}
]
},
"Group": {
"GroupArn": "arn:aws:resource-groups:sa-east-1:123456789012:group/MyCRGroup",
"Name": "MyCRGroup"
}
}
Add a Capacity Reservation to a group
If you add a Capacity Reservation that is shared with you to a group, and that Capacity Reservation is unshared, it is automatically removed from the group.
To add a Capacity Reservation to a group
Use the group-resources
Amazon CLI command. For group
, specify the name of the group to which to add the Capacity Reservations, and for resources
,
specify ARNs of the Capacity Reservations to add. To add multiple Capacity Reservations, separate the ARNs with a space. To get the ARNs of the Capacity Reservations to add, use the
describe-capacity-reservations Amazon CLI command and specify the IDs of the Capacity Reservations.
For example, the following command adds two Capacity Reservations to a group named MyCRGroup
.
C:\>
aws resource-groups group-resources --groupMyCRGroup
--resource-arnsarn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-1234567890abcdef1
arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-54321abcdef567890
The following shows example output.
{
"Failed": [],
"Succeeded": [
"arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-1234567890abcdef1",
"arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-54321abcdef567890"
]
}
View Capacity Reservations in a group
To view the Capacity Reservations in a specific group
Use the list-group-resources Amazon CLI command. For group
, specify the name of the
group.
For example, the following command lists the Capacity Reservations in a group named MyCRGroup
.
C:\>
aws resource-groups list-group-resources --groupMyCRGroup
The following shows example output.
{
"QueryErrors": [],
"ResourceIdentifiers": [
{
"ResourceType": "AWS::EC2::CapacityReservation",
"ResourceArn": "arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-1234567890abcdef1"
},
{
"ResourceType": "AWS::EC2::CapacityReservation",
"ResourceArn": "arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-54321abcdef567890"
}
]
}
Note
The command output includes Capacity Reservations that you own and Capacity Reservations that are shared with you.
View the groups to which a Capacity Reservation belongs
Remove a Capacity Reservation from a group
To remove a Capacity Reservation from a group
Use the ungroup-resources Amazon CLI command. For group
, specify the ARN of the
group from which to remove the Capacity Reservation, and for resources
specify the ARNs of the Capacity Reservations to remove.
To remove multiple Capacity Reservations, separate the ARNs with a space.
The following example removes two Capacity Reservations from a group named MyCRGroup
.
C:\>
aws resource-groups ungroup-resources --groupMyCRGroup
--resource-arnsarn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-0e154d26a16094dd
arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-54321abcdef567890
The following shows example output.
{
"Failed": [],
"Succeeded": [
"arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-0e154d26a16094dd",
"arn:aws:ec2:sa-east-1:123456789012:capacity-reservation/cr-54321abcdef567890"
]
}
Delete a Capacity Reservation group
To delete a group
Use the delete-group Amazon CLI command. For group
, provide the name of the
group to delete.
For example, the following command deletes a group named MyCRGroup
.
C:\>
aws resource-groups delete-group --groupMyCRGroup
The following shows example output.
{
"Group": {
"GroupArn": "arn:aws:resource-groups:sa-east-1:123456789012:group/MyCRGroup",
"Name": "MyCRGroup"
}
}