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

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, Availability Zone, and tenancy) 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, Availability Zone, and tenancy) 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.

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:

For example, the following command creates a group named MyCRGroup.

aws resource-groups create-group --name MyCRGroup --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.

aws resource-groups group-resources --group MyCRGroup --resource-arns arn: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.

aws resource-groups list-group-resources --group MyCRGroup

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"
        }
    ]
}

View the groups to which a Capacity Reservation belongs

Amazon CLI

To view the groups to which a specific Capacity Reservation has been added

Use the get-groups-for-capacity-reservation Amazon CLI command.

For example, the following command lists the groups to which Capacity Reservation cr-1234567890abcdef1 has been added.

aws ec2 get-groups-for-capacity-reservation --capacity-reservation-id cr-1234567890abcdef1

The following shows example output.

{
    "CapacityReservationGroups": [
        {
            "OwnerId": "123456789012",
            "GroupArn": "arn:aws:resource-groups:sa-east-1:123456789012:group/MyCRGroup"
        }
    ]
}

Note

If you specify a Capacity Reservation that is shared with you, the command returns only Capacity Reservation groups that you own.

Amazon EC2 console

To view the groups to which a specific Capacity Reservation has been added

1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

2. In the navigation pane, choose Capacity Reservations, select the Capacity Reservation to view, and then choose View.

   The groups to which the Capacity Reservation has been added are listed in the Groups card.

Note

If you choose a Capacity Reservation that is shared with you, the console displays only Capacity Reservation groups that you own.

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.

aws resource-groups ungroup-resources --group MyCRGroup --resource-arns arn: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.

aws resource-groups delete-group --group MyCRGroup

The following shows example output.

{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:sa-east-1:123456789012:group/MyCRGroup",
        "Name": "MyCRGroup"
    }
}