Create a Capacity Reservation

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Uniform scale set ✔️ Flexible scale sets

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

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 results in an error.
• The VM size must be available in the target region. Otherwise, the reservation creation fails.
• The subscription must have available 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.
  • As needed to satisfy existing quota limits, single VMs can be done in stages. Create a capacity reservation with a smaller quantity and reallocate that quantity of virtual machines. This frees up quota to increase the quantity reserved and add more virtual machines. Alternatively, if the subscription uses different VM sizes in the same series, reserve and redeploy VMs for the first size. Then add a reservation to the group for another size and redeploy the VMs for the new size to the reservation group. Repeat until complete.
  • For Scale Sets, available quota is required unless the Scale Set or you delete its VM instances, capacity is reserved, and the Scale Set instances are added using reserved capacity. If the Scale Set is updated using blue green deployment, then reserve the capacity and deploy the new Scale Set to the reserved capacity at the next update.
• 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 results 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.

Checking VM sizes available for Capacity Reservation in a region

Before creating capacity reservation, VM sizes available for reservation can be checked for a particular region.

Portal

1. Open Azure portal
2. In the search bar, type Capacity Reservation groups
3. Select Capacity Reservation groups from the options
4. Select Create
5. Under the Basics tab, create a Capacity Reservation group:
   1. Select a Subscription
   2. Select or create a Resource group
   3. Name your group
   4. Select a Region
   5. Optionally select Availability zones or opt not to specify any zones and allow Azure to choose for you
6. Select Next
7. On VM size, click on See all sizes to check what VM sizes are available for Capacity Reservation

CLI

Before you create a capacity reservation, you can check the reservation available VM sizes for the region selected. The following example lists the capacity reservation available VM sizes in East US location using Azure CLI:

 az vm list-skus -l eastus --resource-type virtualMachines --query "[?contains(capabilities[?name == 'CapacityReservationSupported' && value == 'True'].name,'CapacityReservationSupported')].name"

PowerShell

Before you create a capacity reservation, you can check the reservation available VM sizes for the region selected using Get-AzComputeResourceSku for Capability property for Resource type Virtual Machines. The following example lists the capacity reservation available VM sizes in East US location:

 $vmsizes = Get-AzComputeResourceSku -Location eastus | where {$_.ResourceType -eq "virtualMachines"}
 foreach($vmsize in $vmsizes) { foreach($capability in $vmsize.capabilities) {  if($capability.Name -eq 'CapacityReservationSupported' -and $capability.Value -eq 'true'){ $vmsize.name  } } }

Create a Capacity Reservation

API

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 parameter:

   { 
     "location":"eastus"
   } 
   

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

   The group in the following example only supports regional reservations, because zones weren't specified at the time of creation. To create a zonal group, pass an extra parameter zone in the request body:

   { 
     "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 parameters:

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

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

Portal

1. Open Azure portal
2. In the search bar, type Capacity Reservation groups
3. Select Capacity Reservation groups from the options
4. Select Create
5. Under the Basics tab, create a Capacity Reservation group:
   1. Select a Subscription
   2. Select or create a Resource group
   3. Name your group
   4. Select a Region
   5. Optionally select Availability zones or opt not to specify any zones and allow Azure to choose for you
6. Select Next
7. Under the Reservations tab, create at least one Capacity Reservation:
   1. Give each reservation a Reservation Name, the quantity of VM Instances, and select a unique VM size
   2. The Cost/month column will display billing information based on your selections
8. Select Next
9. Under the Tags tab, optionally create tags
10. Select Next
11. Under the Review + Create tab, review your Capacity Reservation group information
12. Select Create

CLI

1. Before you can create a Capacity Reservation, create a resource group with az group create. The following example creates a resource group myResourceGroup in the East US location.

   az group create 
   -l eastus 
   -g myResourceGroup
   

2. Now create a Capacity Reservation group with az capacity reservation group create. The following example creates a group myCapacityReservationGroup in the East US location for all three availability zones.

   az capacity reservation group create 
   -n myCapacityReservationGroup 
   -l eastus 
   -g myResourceGroup 
   --zones 1 2 3 
   

3. Once the Capacity Reservation group is created, create a new Capacity Reservation with az capacity reservation create. The following example creates myCapacityReservation for five quantities of Standard_D2s_v3 VM size in Zone 1 of East US location.

   az capacity reservation create 
   -c myCapacityReservationGroup 
   -n myCapacityReservation 
   -l eastus 
   -g myResourceGroup 
   --sku Standard_D2s_v3 
   --capacity 5 
   --zone 1
   

PowerShell

1. Before you can create a Capacity Reservation, create a resource group with New-AzResourceGroup. The following example creates a resource group myResourceGroup in the East US location.

   New-AzResourceGroup
   -ResourceGroupName "myResourceGroup"
   -Location "eastus"
   

2. Now create a Capacity Reservation group with New-AzCapacityReservationGroup. The following example creates a group myCapacityReservationGroup in the East US location for all three availability zones.

   New-AzCapacityReservationGroup
   -ResourceGroupName "myResourceGroup"
   -Location "eastus"
   -Zone "1","2","3"
   -Name "myCapacityReservationGroup"
   

3. Once the Capacity Reservation group is created, create a new Capacity Reservation with New-AzCapacityReservation. The following example creates myCapacityReservation for five quantities of Standard_D2s_v3 VM size in Zone 1 of East US location.

   New-AzCapacityReservation
   -ResourceGroupName "myResourceGroup"
   -Location "eastus"
   -Zone "1"
   -ReservationGroupName "myCapacityReservationGroup"
   -Name "myCapacityReservation"
   -Sku "Standard_D2s_v3"
   -CapacityToReserve 5
   

To learn more, go to Azure PowerShell commands New-AzResourceGroup, New-AzCapacityReservationGroup, and New-AzCapacityReservation.

ARM template

An ARM template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. In declarative syntax, you describe your intended deployment without writing the sequence of programming commands to create the deployment.

ARM templates let you deploy groups of related resources. In a single template, you can create Capacity Reservation group and Capacity Reservations. You can deploy templates through the Azure portal, Azure CLI, or Azure PowerShell, or from continuous integration/continuous delivery (CI/CD) pipelines.

If your environment meets the prerequisites and you're familiar with using ARM templates, use any of the following templates:

• Create Zonal Capacity Reservation
• Create VM with Capacity Reservation
• Create Virtual Machine Scale Sets with Capacity Reservation

Check on your Capacity Reservation

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

API

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

CLI

az capacity reservation show 
-c myCapacityReservationGroup 
-n myCapacityReservation 
-g myResourceGroup

PowerShell

Check on your Capacity Reservation:

Get-AzCapacityReservation
-ResourceGroupName <"ResourceGroupName">
-ReservationGroupName <"CapacityReservationGroupName">
-Name <"CapacityReservationName">

To find the VM size and the quantity reserved, use the following command:

$CapRes =
Get-AzCapacityReservation
-ResourceGroupName <"ResourceGroupName">
-ReservationGroupName <"CapacityReservationGroupName">
-Name <"CapacityReservationName">

$CapRes.sku

To learn more, go to Azure PowerShell command Get-AzCapacityReservation.

Portal

1. Open Azure portal
2. In the search bar, type Capacity Reservation groups
3. Select Capacity Reservation groups from the options
4. From the list, select the Capacity Reservation group name you just created
5. Select Overview
6. Select Reservations
7. In this view, you are able to see all the reservations in the group along with the VM size and quantity reserved

Next steps

Learn how to modify your Capacity Reservation