AWS Cloud Operations Blog

Target a group of Amazon EC2 On-Demand Capacity Reservations

On-Demand Capacity Reservations enable you to reserve capacity for Amazon Elastic Compute Cloud(Amazon EC2) instances in an Availability Zone for any duration. You can use AWS Resource Groups to organize AWS resources into logical collections of applications, projects or environments.

Last year, we introduced the ability to target EC2 capacity reservations in a resource group by using the resource group’s ARN. This helps you easily collect capacity reservations into a resource group and then launch EC2 instances that target this group.

As an example, you can use Resource Groups to control which EC2 instances can occupy a capacity reservation. You might not want to use Capacity Reservations with the default Open instance matching option that matches them to any instance. At the same time, you might not want to specify an individual CapacityReservationId at every instance launch. Using Resource Groups with Capacity Reservations provides a coarse-grained mechanism to categorize capacity reservations and isolate reservation usage across multiple workloads or environments.

In this blog post, I show you how to organize Capacity Reservations using AWS Resource Groups and launch EC2 instances by targeting the group.

As you follow this example, you will perform the following steps:

  1. Create capacity reservations used for launching EC2 instances.
  2. Group capacity reservations using AWS Resource Groups.
  3. Launch EC2 instances that target the resource group.

Walkthrough

To perform these steps, you must have the AWS CLI installed and configured for the AWS account.

Step 1: Create capacity reservations used for launching EC2 instances

Choose an Availability Zone to create the capacity reservations. Use the same Availability Zone in all the commands in this post. In this example, I use us-east-1a. To proceed further, you need the ARNs of the created capacity reservations. Use the create-capacity-reservation AWS CLI command and make a note of CapacityReservationArn values in the output.

$ aws ec2 create-capacity-reservation --instance-type t2.micro --instance-platform Linux/UNIX --instance-match-criteria targeted --availability-zone us-east-1a --instance-count 2
$ aws ec2 create-capacity-reservation --instance-type t2.small --instance-platform 'Red Hat Enterprise Linux' --instance-match-criteria targeted --availability-zone us-east-1a --instance-count 2
$ aws ec2 create-capacity-reservation --instance-type t2.micro --instance-platform 'Red Hat Enterprise Linux' --instance-match-criteria targeted --availability-zone us-east-1a --instance-count 2

Now that the required resources have been created, you can use AWS Resource Groups to group the capacity reservations.

Step 2: Group capacity reservations using AWS Resource Groups

Use the create-group command to create a resource group named EC2CRGroup that can contain only capacity reservations.

$ aws resource-groups create-group --name EC2CRGroup --configuration '{"Type":"AWS::EC2::CapacityReservationPool"}' '{"Type":"AWS::ResourceGroups::Generic", "Parameters": [{"Name": "allowed-resource-types", "Values": ["AWS::EC2::CapacityReservation"]}]}'

Use the CapacityReservationArn values you noted earlier. Use the group-resources command to add the capacity reservations to EC2CRGroup. In the output, under the Succeeded key, you should see the list of capacity reservation ARNs. This indicates the success of the operation.

$ aws resource-groups group-resources --group EC2CRGroup --resource-arns arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128abc arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128def arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128ghi
{
    "Succeeded": [
        "arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128abc",
        "arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128def",
        "arn:aws:ec2:us-east-1:012345678901:capacity-reservation/cr-01234567890128ghi"
    ],
    "Failed": [],
    "Pending": []
}

Now that the capacity reservations are created and grouped in a resource group, you can launch EC2 instances that target that resource group.

Step 3: Launch EC2 instances that target the resource group

You can launch EC2 instances by targeting EC2CRGroup. Instances that target a group of capacity reservations match any capacity reservation in the group with matching attributes (instance type, platform, and Availability Zone) that has 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 already launched instance is automatically matched with and moved into its reserved capacity.

You can launch the instances into a default subnet of Amazon Virtual Private Cloud(Amazon VPC) in your account. To do this, first run the describe-vpcs command, find the VPC that has IsDefault flag set to true, and make a note of the VpcId.

$ aws ec2 describe-vpcs --no-paginate --filters Name=isDefault,Values=true --query 'Vpcs[].VpcId'
[
    "vpc-abcd0123"
]

Next, use the describe-subnets command to get the subnets in this VPC. Find the subnet that has DefaultForAz flag set to true and AvailabilityZone matching the Availability Zone you chose when you created the capacity reservations. Make a note of the SubnetId.

$ aws ec2 describe-subnets --no-paginate --filters Name=vpc-id,Values=vpc-abcd0123 Name=default-for-az,Values=true Name=state,Values=available Name=availability-zone,Values=us-east-1a --query 'Subnets[].SubnetId'
[
    "SubnetId": "subnet-abcd0123"
]

Now you are ready to launch EC2 instances into the resource group. Use the describe-images command with the necessary filters to choose an AMI for Linux (say ami-linux) and an AMI for Red Hat Enterprise Linux (say ami-rhel).  Use the run-instances command and specify the resource group ARN in --capacity-reservation-specification flag to launch the instances into the group. Make a note of the instance-ids in the output.

$ aws ec2 run-instances --image-id ami-linux --count 1 --instance-type t2.micro --subnet-id subnet-abcd0123 --capacity-reservation-specification CapacityReservationTarget={CapacityReservationResourceGroupArn=arn:aws:resource-groups:us-east-1:012345678901:group/EC2CRGroup}
$ aws ec2 run-instances --image-id ami-rhel --count 1 --instance-type t2.small --subnet-id subnet-abcd0123 --capacity-reservation-specification CapacityReservationTarget={CapacityReservationResourceGroupArn=arn:aws:resource-groups:us-east-1:012345678901:group/EC2CRGroup}
$ aws ec2 run-instances --image-id ami-rhel --count 1 --instance-type t2.micro --subnet-id subnet-abcd0123 --capacity-reservation-specification CapacityReservationTarget={CapacityReservationResourceGroupArn=arn:aws:resource-groups:us-east-1:012345678901:group/EC2CRGroup}

To check that the EC2 instances are using the reserved capacity, run the describe-instances command.

$ aws ec2 describe-instances --instance-ids i-instanceid1 i-instanceid2 i-instanceid3

In the output, you should see each instance mapped to the correct capacity reservation based on the platform and instance type.

Cleanup

Use the terminate-instances command to terminate the launched EC2 instances.

$ aws ec2 terminate-instances --instance-ids i-instanceid1 i-instanceid2 i-instanceid3

Use the cancel-capacity-reservation command to cancel the capacity reservations.

$ aws ec2 cancel-capacity-reservation --capacity-reservation-id cr-01234567890128abc
$ aws ec2 cancel-capacity-reservation --capacity-reservation-id cr-01234567890128def
$ aws ec2 cancel-capacity-reservation --capacity-reservation-id cr-01234567890128ghi

Use the delete-group command to delete the resource group.

$ aws resource-groups delete-group --group EC2CRGroup

Conclusion

In this post, I showed you how to use AWS Resource Groups to organize EC2 capacity reservations and launch EC2 instances that target the resource group.

For more information, see these resources:

About the Author

Chaitanya Nibhanupudi

Chaitanya Nibhanupudi is a Software Development Engineer at AWS Resource Groups. In this role, he builds software with his team to help customers manage their AWS resources. His hobbies include reading books, playing badminton and cricket.