# Capacity Reservation Fleets An *On-Demand Capacity Reservation Fleet* is a group of Capacity Reservations. A Capacity Reservation Fleet request contains all of the configuration information that's needed to launch a Capacity Reservation Fleet. Using a single request, you can reserve large amounts of Amazon EC2 capacity for your workload across multiple instance types, up to a target capacity that you specify. After you create a Capacity Reservation Fleet, you can manage the Capacity Reservations in the fleet collectively by modifying or canceling the Capacity Reservation Fleet. **Topics** + [ ## How Capacity Reservation Fleets work ](#cr-how-it-works) + [ ## Considerations ](#considerations) + [ ## Pricing ](#pricing) + [Concepts and planning](crfleet-concepts.md) + [Create](create-crfleet.md) + [Modify](modify-crfleet.md) + [Cancel](cancel-crfleet.md) + [Example configurations](crfleet-example-configs.md) + [Using service-linked roles](using-service-linked-roles.md) ## How Capacity Reservation Fleets work When you create a Capacity Reservation Fleet, the Fleet attempts to create individual Capacity Reservations to meet the total target capacity that you specified in the Fleet request. The number of instances for which the Fleet reserves capacity depends on the [*total target capacity*](crfleet-concepts.md#target-capacity) and the [*instance type weights*](crfleet-concepts.md#instance-weight) that you specify. The instance type for which it reserves capacity depends on the [*allocation strategy*](crfleet-concepts.md#allocation-strategy) and [*instance type priorities*](crfleet-concepts.md#instance-priority) that you use. If there is insufficient capacity at the time the Fleet is created, and it is unable to immediately meet its total target capacity, the Fleet asynchronously attempts to create Capacity Reservations until it has reserved the requested amount of capacity. When the Fleet reaches its total target capacity, it attempts to maintain that capacity. If a Capacity Reservation in the Fleet is cancelled, the Fleet automatically creates one or more Capacity Reservations, depending on your Fleet configuration, to replace the lost capacity and to maintain its total target capacity. The Capacity Reservations in the Fleet can't be managed individually. They must be managed collectively by modifying the Fleet. When you modify a Fleet, the Capacity Reservations in the Fleet are automatically updated to reflect the changes. Currently, Capacity Reservation Fleets support the `open` instance matching criteria, and all Capacity Reservations launched by a Fleet automatically use this instance matching criteria. With this criteria, new instances and existing instances that have matching attributes (instance type, platform, Availability Zone, and tenancy) automatically run in the Capacity Reservations created by a Fleet. Capacity Reservation Fleets do not support targeted instance matching criteria. ## Considerations Keep the following in mind when working with Capacity Reservation Fleets: + A Capacity Reservation Fleet can be created, modified, viewed, and cancelled using the AWS CLI and AWS API. + The Capacity Reservations in a Fleet can't be managed individually. They must be managed collectively by modifying or cancelling the Fleet. + A Capacity Reservation Fleet can't span across Regions. + A Capacity Reservation Fleet can't span across Availability Zones. + Capacity Reservations created by a Capacity Reservation Fleet are automatically tagged with the following AWS generated tag: + Key — `aws:ec2-capacity-reservation-fleet` + Value — `fleet_id` You can use this tag to identify Capacity Reservations that were created by a Capacity Reservation Fleet. ## Pricing There are no additional charges for using Capacity Reservation Fleets. You are billed for the individual Capacity Reservations that are created by your Capacity Reservation Fleets. For more information about how Capacity Reservations are billed, see [Capacity Reservation pricing and billing](capacity-reservations-pricing-billing.md). # Capacity Reservation Fleet concepts and planning The following information describes how to plan a Capacity Reservation Fleet and describes Capacity Reservation Fleet concepts including total target capacity, allocation strategy, instance type weight, and instance type priority. **Topics** + [ ## Plan a Capacity Reservation Fleet ](#plan-cr-fleet) + [ ## Total target capacity ](#target-capacity) + [ ## Allocation strategy ](#allocation-strategy) + [ ## Instance type weight ](#instance-weight) + [ ## Instance type priority ](#instance-priority) ## Plan a Capacity Reservation Fleet When planning your Capacity Reservation Fleet, we recommend that you do the following: 1. Determine the amount of compute capacity that is needed by your workload. 1. Decide on the instance types and Availability Zones that you want to use. 1. Assign each instance type a priority based on your needs and preferences. For more information, see [Instance type priority](#instance-priority). 1. Create a capacity weighting system that makes sense for your workload. Assign a weight to each instance type and determine your total target capacity. For more information, see [Instance type weight](#instance-weight) and [Total target capacity](#target-capacity). 1. Determine whether you need the Capacity Reservation indefinitely or only for a specific period of time. ## Total target capacity The *total target capacity* defines the total amount of compute capacity that the Capacity Reservation Fleet reserves. You specify the total target capacity when you create the Capacity Reservation Fleet. After the Fleet has been created, Amazon EC2 automatically creates Capacity Reservations to reserve capacity up to the total target capacity. The number of instances for which the Capacity Reservation Fleet reserves capacity is determined by the total target capacity and the *instance type weight* that you specify for each instance type in the Capacity Reservation Fleet (`total target capacity`/`instance type weight`=`number of instances`). You can assign a total target capacity based on units that are meaningful to your workload. For example, if your workload requires a certain number of vCPUs, you can assign the total target capacity based on the number of vCPUs required. If your workload requires `2048` vCPUs, specify a total target capacity of `2048` and then assign instance type weights based on the number of vCPUs provided by the instance types in the Fleet. For an example, see [Instance type weight](#instance-weight). ## Allocation strategy The allocation strategy for your Capacity Reservation Fleet determines how it fulfills your request for reserved capacity from the instance type specifications in the Capacity Reservation Fleet configuration. Currently, only the `prioritized` allocation strategy is supported. With this strategy, the Capacity Reservation Fleet creates Capacity Reservations using the priorities that you have assigned to each of the instance type specifications in the Capacity Reservation Fleet configuration. Lower priority values indicate higher priority for use. For example, say you create a Capacity Reservation Fleet that uses the following instance types and priorities: + `m4.16xlarge` — priority = 1 + `m5.16xlarge` — priority = 3 + `m5.24xlarge` — priority = 2 The Fleet first attempts to create Capacity Reservations for `m4.16xlarge`. If Amazon EC2 has insufficient `m4.16xlarge` capacity, the Fleet attempts to create Capacity Reservations for `m5.24xlarge`. If Amazon EC2 has insufficient `m5.24xlarge` capacity, the Fleet creates Capacity Reservations for `m5.16xlarge`. ## Instance type weight The *instance type weight* is a weight that you assign to each instance type in the Capacity Reservation Fleet. The weight determines how many units of capacity each instance of that specific instance type counts toward the Fleet's *total target capacity*. You can assign weights based on units that are meaningful to your workload. For example, if your workload requires a certain number of vCPUs, you can assign weights based on the number of vCPUs provided by each instance type in the Capacity Reservation Fleet. In this case, if you create a Capacity Reservation Fleet using `m4.16xlarge` and `m5.24xlarge` instances, you would assign weights that correspond to the number of vCPUs for each instance as follows: + `m4.16xlarge` — `64` vCPUs, weight = `64` units + `m5.24xlarge` — `96` vCPUs, weight = `96` units The instance type weight determines the number of instances for which the Capacity Reservation Fleet reserves capacity. For example, if a Capacity Reservation Fleet with a total target capacity of `384` units uses the instance types and weights in the preceding example, the Fleet could reserve capacity for `6` `m4.16xlarge` instances (384 total target capacity/64 instance type weight=6 instances), or `4` `m5.24xlarge` instances (384 / 96 = 4). If you do not assign instance type weights, or if you assign an instance type weight of `1`, the total target capacity is based purely on instance count. For example, if a Capacity Reservation Fleet with a total target capacity of `384` units uses the instance types in the preceding example, but omits the weights or specifies a weight of `1` for both instance types, the Fleet could reserve capacity for either `384` `m4.16xlarge` instances or `384` `m5.24xlarge` instances. ## Instance type priority The *instance type priority* is a value that you assign to the instance types in the Fleet. The priorities are used to determine which of the instance types specified for the Fleet should be prioritized for use. Lower priority values indicate a higher priority for use. # Create a Capacity Reservation Fleet When you create a Capacity Reservation Fleet it automatically creates Capacity Reservations for the instance types specified in the Fleet request, up to the specified total target capacity. The number of instances for which the Capacity Reservation Fleet reserves capacity depends on the total target capacity and instance type weights that you specify in the request. For more information, see [Instance type weight](crfleet-concepts.md#instance-weight) and [Total target capacity](crfleet-concepts.md#target-capacity). When you create the Fleet, you must specify the instance types to use and a priority for each of those instance types. For more information, see [Allocation strategy](crfleet-concepts.md#allocation-strategy) and [Instance type priority](crfleet-concepts.md#instance-priority). **Note** The **AWSServiceRoleForEC2CapacityReservationFleet** service-linked role is automatically created in your account the first time that you create a Capacity Reservation Fleet. For more information, see [Using service-linked roles for Capacity Reservation FleetUsing service-linked roles for EC2 Capacity Manager](using-service-linked-roles.md). Currently, Capacity Reservation Fleets support the `open` instance matching criteria only. ------ #### [ AWS CLI ] **To create a Capacity Reservation Fleet** Use the [create-capacity-reservation-fleet](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-capacity-reservation-fleet.html) command. ``` aws ec2 create-capacity-reservation-fleet \ --total-target-capacity 24 \ --allocation-strategy prioritized \ --instance-match-criteria open \ --tenancy default \ --end-date 2021-12-31T23:59:59.000Z \ --instance-type-specifications file://instanceTypeSpecification.json ``` The following are the contents of `instanceTypeSpecification.json`. ``` [ { "InstanceType": "m5.xlarge", "InstancePlatform": "Linux/UNIX", "Weight": 3.0, "AvailabilityZone":"us-east-1a", "EbsOptimized": true, "Priority" : 1 } ] ``` The following is example output. ``` { "Status": "submitted", "TotalFulfilledCapacity": 0.0, "CapacityReservationFleetId": "crf-abcdef01234567890", "TotalTargetCapacity": 24 } ``` ------ #### [ PowerShell ] **To create a Capacity Reservation Fleet** Use the [New-EC2CapacityReservationFleet](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2CapacityReservationFleet.html) cmdlet. ``` New-EC2CapacityReservationFleet ` -TotalTargetCapacity 24 ` -AllocationStrategy "prioritized" ` -InstanceMatchCriterion "open" ` -Tenancy "default" ` -EndDate 2021-12-31T23:59:59.000Z ` -InstanceTypeSpecification $specification ``` The specification is defined as follows. ``` $specification = New-Object Amazon.EC2.Model.ReservationFleetInstanceSpecification $specification.InstanceType = "m5.xlarge" $specification.InstancePlatform = "Linux/UNIX" $specification.Weight = 3.0 $specification.AvailabilityZone = "us-east-1a" $specification.EbsOptimized = $true $specification.Priority = 1 ``` ------ # Modify a Capacity Reservation Fleet You can modify the total target capacity and date of a Capacity Reservation Fleet at any time. When you modify the total target capacity of a Capacity Reservation Fleet, the Fleet automatically creates new Capacity Reservations, or modifies or cancels existing Capacity Reservations in the Fleet to meet the new total target capacity. When you modify the end date for the Fleet, the end dates for all of the individual Capacity Reservations are updated accordingly. **Considerations** + After you modify a Fleet, its status transitions to `modifying`. You can't attempt additional modifications to a Fleet while it is in the `modifying` state. + You can't modify the tenancy, Availability Zone, instance types, instance platforms, priorities, or weights used by a Capacity Reservation Fleet. If you need to change any of these parameters, you might need to cancel the existing Fleet and create a new one with the required parameters. + You can't specify `--end-date` and `--remove-end-date` in the same command. ------ #### [ AWS CLI ] **To modify a Capacity Reservation Fleet** Use the [modify-capacity-reservation-fleet](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-capacity-reservation-fleet.html) command. **Example 1: Modify total target capacity** ``` aws ec2 modify-capacity-reservation-fleet \ --capacity-reservation-fleet-id crf-01234567890abcedf \ --total-target-capacity 160 ``` **Example 2: Modify end date** ``` aws ec2 modify-capacity-reservation-fleet \ --capacity-reservation-fleet-id crf-01234567890abcedf \ --end-date 2021-07-04T23:59:59.000Z ``` **Example 3: Remove end date** ``` aws ec2 modify-capacity-reservation-fleet \ --capacity-reservation-fleet-id crf-01234567890abcedf \ --remove-end-date ``` ------ #### [ PowerShell ] **To modify a Capacity Reservation Fleet** Use the [Edit-EC2CapacityReservationFleet](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2CapacityReservationFleet.html) cmdlet. **Example 1: Modify total target capacity** ``` Edit-EC2CapacityReservationFleet ` -CapacityReservationFleetId crf-01234567890abcedf ` -TotalTargetCapacity 160 ``` **Example 2: Modify end date** ``` Edit-EC2CapacityReservationFleet ` -CapacityReservationFleetId crf-01234567890abcedf ` -EndDate 2021-07-04T23:59:59.000Z ``` **Example 3: Remove end date** ``` Edit-EC2CapacityReservationFleet ` -CapacityReservationFleetId crf-01234567890abcedf ` -RemoveEndDate ``` ------ # Cancel a Capacity Reservation Fleet When you no longer need a Capacity Reservation Fleet and the capacity it reserves, you can cancel it. When you cancel a Fleet, its status changes to `cancelled` and it can no longer create new Capacity Reservations. Additionally, all of the individual Capacity Reservations in the Fleet are canceled. The instances that were previously running in the reserved capacity continue to run normally in the shared capacity. ------ #### [ AWS CLI ] **To cancel a Capacity Reservation Fleet** Use the [cancel-capacity-reservation-fleets](https://docs.aws.amazon.com/cli/latest/reference/ec2/cancel-capacity-reservation-fleets.html) command. ``` aws ec2 cancel-capacity-reservation-fleets \ --capacity-reservation-fleet-ids crf-abcdef01234567890 ``` The following is example output. ``` { "SuccessfulFleetCancellations": [ { "CurrentFleetState": "cancelling", "PreviousFleetState": "active", "CapacityReservationFleetId": "crf-abcdef01234567890" } ], "FailedFleetCancellations": [] } ``` ------ #### [ PowerShell ] **To cancel a Capacity Reservation Fleet** Use the [Stop-EC2CapacityReservationFleet](https://docs.aws.amazon.com/powershell/latest/reference/items/Stop-EC2CapacityReservationFleet.html) cmdlet. ``` Stop-EC2CapacityReservationFleet ` -CapacityReservationFleetId crf-abcdef01234567890 ``` ------ # Example Capacity Reservation Fleet configurations The following example creates a Capacity Reservation Fleet that uses two instance types: `m5.4xlarge` and `m5.12xlarge`. It uses a weighting system based on the number of vCPUs provided by the specified instance types. The total target capacity is `480` vCPUs. The `m5.4xlarge` provides 16 vCPUs and gets a weight of `16`, while the `m5.12xlarge` provides 48 vCPUs and gets a weight of `48`. This weighting system configures the Capacity Reservation Fleet to reserve capacity for either 30 `m5.4xlarge` instances (480/16=30), or 10 `m5.12xlarge` instances (480/48=10). The Fleet is configured to prioritize the `m5.12xlarge` capacity and gets priority of `1`, while the `m5.4xlarge` gets a lower priority of `2`. This means that the fleet will attempt to reserve the `m5.12xlarge` capacity first, and only attempt to reserve the `m5.4xlarge` capacity if Amazon EC2 has insufficient `m5.12xlarge` capacity. The Fleet reserves the capacity for `Windows` instances and the reservation automatically expires on `October 31, 2021` at `23:59:59` UTC. ``` aws ec2 create-capacity-reservation-fleet \ --total-target-capacity 480 \ --allocation-strategy prioritized \ --instance-match-criteria open \ --tenancy default \ --end-date 2021-10-31T23:59:59.000Z \ --instance-type-specifications file://instanceTypeSpecification.json ``` The following is the contents of `instanceTypeSpecification.json`. ``` [ { "InstanceType": "m5.4xlarge", "InstancePlatform":"Windows", "Weight": 16, "AvailabilityZone":"us-east-1a", "EbsOptimized": true, "Priority" : 2 }, { "InstanceType": "m5.12xlarge", "InstancePlatform":"Windows", "Weight": 48, "AvailabilityZone":"us-east-1a", "EbsOptimized": true, "Priority" : 1 } ] ``` # Using service-linked roles for Capacity Reservation Fleet On-Demand Capacity Reservation Fleet uses AWS Identity and Access Management (IAM) [service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_terms-and-concepts). A service-linked role is a unique type of IAM role that is linked directly to Capacity Reservation Fleet. Service-linked roles are predefined by Capacity Reservation Fleet and include all the permissions that the service requires to call other AWS services on your behalf. A service-linked role makes setting up Capacity Reservation Fleet easier because you don’t have to manually add the necessary permissions. Capacity Reservation Fleet defines the permissions of its service-linked roles, and unless defined otherwise, only Capacity Reservation Fleet can assume its roles. The defined permissions include the trust policy and the permissions policy, and that permissions policy cannot be attached to any other IAM entity. You can delete a service-linked role only after first deleting their related resources. This protects your Capacity Reservation Fleet resources because you can't inadvertently remove permission to access the resources. ## Service-linked role permissions for Capacity Reservation Fleet Capacity Reservation Fleet uses the service-linked role named **AWSServiceRoleForEC2CapacityReservationFleet** to create, describe, modify, and cancel Capacity Reservations in a Capacity Reservation Fleet on your behalf. The AWSServiceRoleForEC2CapacityReservationFleet service-linked role trusts the following entity to assume the role: + `capacity-reservation-fleet.amazonaws.com` The role uses the `AWSEC2CapacityReservationFleetRolePolicy` AWS managed policy. For more information, see [AWS managed policy: AWSEC2CapacityReservationFleetRolePolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSEC2CapacityReservationFleetRolePolicy). You must configure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or delete a service-linked role. For more information, see [Service-linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create-service-linked-role.html#service-linked-role-permissions) in the *IAM User Guide*. ## Create a service-linked role for Capacity Reservation Fleet You don't need to manually create a service-linked role. When you create a Capacity Reservation Fleet using the `create-capacity-reservation-fleet` AWS CLI command or the `CreateCapacityReservationFleet` API, the service-linked role is automatically created for you. If you delete this service-linked role, and then need to create it again, you can use the same process to recreate the role in your account. When you create a Capacity Reservation Fleet, Capacity Reservation Fleet creates the service-linked role for you again. ## Edit a service-linked role for Capacity Reservation Fleet Capacity Reservation Fleet does not allow you to edit the AWSServiceRoleForEC2CapacityReservationFleet service-linked role. After you create a service-linked role, you cannot change the name of the role because various entities might reference the role. However, you can edit the description of the role using IAM. For more information, see [Edit a service-linked role description](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-service-linked-role.html#edit-service-linked-role-iam-console) in the *IAM User Guide*. ## Delete a service-linked role for Capacity Reservation Fleet If you no longer need to use a feature or service that requires a service-linked role, we recommend that you delete that role. That way you don’t have an unused entity that is not actively monitored or maintained. However, you must delete the resources for your service-linked role before you can manually delete it. **Note** If the Capacity Reservation Fleet service is using the role when you try to delete the resources, then the deletion might fail. If that happens, wait for a few minutes and try the operation again. **To delete the AWSServiceRoleForEC2CapacityReservationFleet service-linked role** 1. Use the `delete-capacity-reservation-fleet` AWS CLI command or the `DeleteCapacityReservationFleet` API to delete the Capacity Reservation Fleets in your account. 1. Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForEC2CapacityReservationFleet service-linked role. For more information, see [Delete a service-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html#id_roles_manage_delete_slr) in the *IAM User Guide*. ## Supported Regions for Capacity Reservation Fleet service-linked roles Capacity Reservation Fleet supports using service-linked roles in all of the Regions where the service is available. For more information, see [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/ec2-service.html#ec2_region).