Create a Capacity Reservation (preview)

Capacity Reservation is always created as part of a Capacity Reservation Group. The first step is to create a group if a suitable one doesn’t exist already, then create reservations. Once successfully created, reservations are immediately available for use with virtual machines. The capacity is reserved for your use as long as the reservation isn't deleted.

A well-formed request for capacity reservation group should always succeed as it doesn't reserve any capacity. It just acts as a container for reservations. However, a request for capacity reservation could fail if you don't have the required quota for the VM series or if Azure doesn’t have enough capacity to fulfill the request. Either request more quota or try a different VM size, location, or zone combination.

A Capacity Reservation creation succeeds or fails in its entirety. For a request to reserve 10 instances, success is returned only if all 10 could be allocated. Otherwise, the capacity reservation creation will fail.

Important

Capacity Reservation is currently in public preview. This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Considerations

The Capacity Reservation must meet the following rules:

  • The location parameter must match the location property for the parent Capacity Reservation Group. A mismatch will result in an error.
  • The VM size must be available in the target region. Otherwise, the reservation creation will fail.
  • The subscription must have sufficient approved quota equal to or more than the quantity of VMs being reserved for the VM series and for the region overall. If needed, request more quota.
  • Each Capacity Reservation Group can have exactly one reservation for a given VM size. For example, only one Capacity Reservation can be created for the VM size Standard_D2s_v3. Attempt to create a second reservation for Standard_D2s_v3 in the same Capacity Reservation Group will result in an error. However, another reservation can be created in the same group for other VM sizes, such as Standard_D4s_v3, Standard_D8s_v3 and so on.
  • For a Capacity Reservation Group that supports zones, each reservation type is defined by the combination of VM size and zone. For example, one Capacity Reservation for Standard_D2s_v3 in Zone 1, another Capacity Reservation for Standard_D2s_v3 in Zone 2, and a third Capacity Reservation for Standard_D2s_v3 in Zone 3 is supported.

Create a capacity reservation

  1. Create a Capacity Reservation Group

    To create a capacity reservation group, construct the following PUT request on Microsoft.Compute provider:

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/CapacityReservationGroups/{CapacityReservationGroupName}&api-version=2021-04-01
    

    In the request body, include the following:

    { 
      "location":"eastus"
    } 
    

    This group is created to contain reservations for the US East location.

    In this example, the group will support only regional reservations because zones weren't specified at the time of creation. To create a zonal group, pass an extra parameter zones in the request body as shown below:

    { 
      "location":"eastus",
      "zones": ["1", "2", "3"] 
    } 
    
  2. Create a Capacity Reservation

    To create a reservation, construct the following PUT request on Microsoft.Compute provider:

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/CapacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{capacityReservationName}?api-version=2021-04-01 
    

    In the request body, include the following:

    { 
      "location": "eastus", 
      "sku": { 
        "name": "Standard_D2s_v3", 
        "capacity": 5 
      }, 
     "tags": { 
            "environment": "testing" 
    } 
    

    The above request creates a reservation in the East US location for 5 quantities of the D2s_v3 VM size.

Check on your Capacity Reservation

Once successfully created, the Capacity Reservation is immediately available for use with VMs.

GET  
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/CapacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{capacityReservationName}?api-version=2021-04-01
{ 
    "name": "<CapacityReservationName>", 
    "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{CapacityReservationName}", 
    "type": "Microsoft.Compute/capacityReservationGroups/capacityReservations", 
    "location": "eastus", 
    "tags": { 
        "environment": "testing" 
    }, 
    "sku": { 
        "name": "Standard_D2s_v3", 
        "capacity": 5 
    }, 
    "properties": { 
        "reservationId": "<reservationId>", 
         "provisioningTime": "<provisioningTime>", 
         "provisioningState": "Updating" 
    } 
} 

Next steps