Modify a capacity reservation

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

After you create a capacity reservation group and a capacity reservation, you might want to modify your reservations. This article explains how to do the following actions by using the API, the Azure portal, and PowerShell.

• Update the number of instances reserved in a capacity reservation.
• Resize VMs associated to a capacity reservation group.
• Delete the capacity reservation group and capacity reservation.

Update the number of instances reserved

Update the number of virtual machine (VM) instances reserved in a capacity reservation.

Important

In rare cases when Azure can't fulfill the request to increase the quantity reserved for existing capacity reservations, a reservation might go into a Failed state and become unavailable until the quantity is restored to the original amount.

API

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

In the request body, update the capacity property to the new count that you want to reserve:

{
    "sku":
    {
        "capacity": 5
    }
} 

In this example, the capacity property is now set to 5.

Portal

1. Open the Azure portal.
2. Go to your capacity reservation group.
3. Select Overview.
4. Select Reservations.
5. Select Manage Reservation at the top.
6. On the Manage Reservations page, enter the new quantity to be reserved in the Instances field.
7. Select Save.

CLI

To update the quantity reserved, use az capacity reservation update with the updated capacity property.

az capacity reservation update 
-c myCapacityReservationGroup 
-n myCapacityReservation 
-g myResourceGroup2 
--capacity 5

PowerShell

To update the quantity reserved, use New-AzCapacityReservation with the updated capacityToReserve property.

Update-AzCapacityReservation
-ResourceGroupName "myResourceGroup"
-ReservationGroupName "myCapacityReservationGroup"
-Name "myCapacityReservation"
-CapacityToReserve 5

To learn more, see the Azure PowerShell command Update-AzCapacityReservation.

Resize VMs associated to a capacity reservation group

You must do one of the following options if the VM being resized is currently attached to a capacity reservation group and that group doesn't have a reservation for the target size:

• Create a new reservation for that size.
• Remove the VM from the reservation group before you resize.

Check if the target size is part of the reservation group.

API

1. Get the names of all capacity reservations within the group.

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

   { 
       "name": "<CapacityReservationGroupName>", 
       "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{CapacityReservationGroupName}", 
       "type": "Microsoft.Compute/capacityReservationGroups", 
       "location": "eastUS", 
       "zones": [ 
           "1" 
       ], 
       "properties": { 
           "capacityReservations": [ 
               { 
                   "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{capacityReservationName1}" 
               }, 
   { 
                   "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{capacityReservationName2}" 
               } 
           ] 
       } 
   } 
   

2. Find out the VM size reserved for each reservation. The following example is for capacityReservationName1, but you can repeat this step for other reservations.

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

   { 
       "name": "capacityReservationName1", 
       "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{CapacityReservationGroupName}/capacityReservations/{capacityReservationName1}", 
       "type": "Microsoft.Compute/capacityReservationGroups/capacityReservations", 
       "location": "eastUS", 
       "sku": { 
           "name": "Standard_D2s_v3", 
           "capacity": 3 
       }, 
       "zones": [ 
           "1" 
       ], 
       "properties": { 
           "reservationId": "<reservationId>", 
           "provisioningTime": "<provisioningTime>", 
           "provisioningState": "Succeeded" 
       } 
   }  
   

3. Consider the following scenarios:

   • If the target VM size isn't part of the group, create a new capacity reservation for the target VM.
   • If the target VM size already exists in the group, resize the VM.

Portal

1. Open the Azure portal.
2. Go to your capacity reservation group.
3. Select Overview.
4. Select Reservations.
5. Look at the VM size reserved for each reservation.
   1. If the target VM size isn't part of the group, create a new capacity reservation for the target VM.
   2. If the target VM size already exists in the group, resize the VM.

CLI

1. Get the names of all capacity reservations within the capacity reservation group with az capacity reservation group show.

   az capacity reservation group show 
   -g myResourceGroup
   -n myCapacityReservationGroup 
   

2. From the response, find the names of all the capacity reservations.

3. To find out the VM sizes reserved for each reservation, run the following commands:

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

4. Consider the following scenarios:

   • If the target VM size isn't part of the group, create a new capacity reservation for the target VM.
   • If the target VM size already exists in the group, resize the VM.

PowerShell

1. Get the names of all capacity reservations within the group with Get-AzCapacityReservationGroup.

   Get-AzCapacityReservationGroup
   -ResourceGroupName "myResourceGroup"
   -Name "myCapacityReservationGroup"
   

2. From the response, find the names of all the capacity reservations.

3. To find out the VM sizes reserved for each reservation, run the following commands:

   $CapRes =
   Get-AzCapacityReservation
   -ResourceGroupName "myResourceGroup"
   -ReservationGroupName "myCapacityReservationGroup"
   -Name "mycapacityReservation"
   
   $CapRes.Sku
   

4. Consider the following scenarios:

   • If the target VM size isn't part of the group, create a new capacity reservation for the target VM.
   • If the target VM size already exists in the group, resize the VM.

To learn more, see the Azure PowerShell commands Get-AzCapacityReservationGroup and Get-AzCapacityReservation.

Delete a capacity reservation group and capacity reservation

Azure allows a group to be deleted when all the member capacity reservations are deleted and no VMs are associated to the group.

To delete a capacity reservation, first find out all of the VMs that are associated to it. The list of VMs is available under the virtualMachinesAssociated property.

API

First, find all the VMs associated to the capacity reservation group and dissociate them:

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

{ 
    "name": "<capacityReservationGroupName>", 
    "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{capacityReservationGroupName}", 
    "type": "Microsoft.Compute/capacityReservationGroups", 
    "location": "eastus", 
    "properties": { 
        "capacityReservations": [ 
            { 
                "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{capacityReservationGroupName}/capacityReservations/{capacityReservationName}" 
            } 
        ], 
        "virtualMachinesAssociated": [ 
            { 
                "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{VirtualMachineName1}" 
            }, 
            { 
                "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{VirtualMachineName2}" 
            } 
        ], 
        "instanceView": { 
            "capacityReservations": [ 
                { 
                    "name": "{capacityReservationName}", 
                    "utilizationInfo": { 
                        "virtualMachinesAllocated": [ 
                            { 
                                "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{VirtualMachineName1}" 
                            } 
                        ] 
                    }, 
                    "statuses": [ 
                        { 
                            "code": "ProvisioningState/succeeded", 
                            "level": "Info", 
                            "displayStatus": "Provisioning succeeded", 
                            "time": "<time>" 
                        } 
                    ] 
                } 
            ] 
        } 
    } 
}  

From the preceding response, find the names of all the VMs under the virtualMachinesAssociated property. Remove them from the capacity reservation group by using the steps in Remove a VM association to a capacity reservation.

After all the VMs are removed from the capacity reservation group, delete the member capacity reservations:

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

Lastly, delete the parent capacity reservation group:

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

Portal

1. Open the Azure portal.
2. Go to your capacity reservation group.
3. Select Resources.
4. Find out all the VMs that are associated to the group.
5. Disassociate every VM.
6. Delete every capacity reservation in the group:
   1. Go to Reservations.
   2. Select each reservation.
   3. Select Delete.
7. Delete the capacity reservation group:
   1. Go to the capacity reservation group.
   2. Select Delete at the top of the page.

CLI

Find out all the VMs associated to the capacity reservation group and dissociate them.

1. Run the following command:

   az capacity reservation group show
   -g myResourceGroup
   -n myCapacityReservationGroup
   

2. From the preceding response, find out the names of all the VMs under the VirtualMachinesAssociated property and remove them from the capacity reservation group by using the steps in Remove a VM association from a capacity reservation group.

3. Delete the capacity reservation:

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

4. Delete the capacity reservation group:

   az capacity reservation group delete 
   -g myResourceGroup 
   -n myCapacityReservationGroup
   

PowerShell

Find out all the VMs associated to the capacity reservation group and dissociate them.

1. Run the following command:

   Get-AzCapacityReservationGroup
   -ResourceGroupName "myResourceGroup"
   -Name "myCapacityReservationGroup"
   

2. From the preceding response, find out the names of all the VMs under the VirtualMachinesAssociated property. Remove them from the capacity reservation group by using the steps in Remove a VM association from a capacity reservation group.

3. Delete the capacity reservation:

   Remove-AzCapacityReservation
   -ResourceGroupName "myResourceGroup"
   -ReservationGroupName "myCapacityReservationGroup"
   -Name "myCapacityReservation"
   

4. Delete the capacity reservation group:

   Remove-AzCapacityReservationGroup
   -ResourceGroupName "myResourceGroup"
   -Name "myCapacityReservationGroup"
   

To learn more, see the Azure PowerShell commands Get-AzCapacityReservationGroup, Remove-AzCapacityReservation, and Remove-AzCapacityReservationGroup.

Restore instance quantity

A well-formed request for reducing the reserved quantity should always succeed no matter the number of VMs associated to the reservation. However, increasing the reserved quantity might require more quota and for Azure to fulfill the request for more capacity. In a rare scenario in which Azure can't fulfill the request to increase the reserved quantity for existing reservations, the reservation might go into a Failed state and become unavailable until the reserved quantity is restored to the original amount.

Note

If a reservation is in a Failed state, all the VMs that are associated to the reservation continue to work as normal.

For example, let's say myCapacityReservation has 5 instances reserved. You request 5 extra instances, which makes the total reserved quantity equal to 10. However, because of a constrained capacity situation in the region, Azure can't fulfill the extra 5 instances that you requested. In this case, myCapacityReservation fails to meet its intended state of 10 reserved instances and goes into a Failed state.

To resolve this failure, follow these steps to locate the old quantity reserved value:

1. In the Azure portal, go to Application Change Analysis.
2. Select the applicable Subscription, Resource group, and Time range settings in the filters. You can only go back up to 14 days in the past in the Time range filter.
3. Search for the name of the capacity reservation.
4. Look for the change in the sku.capacity property for that reservation. The old quantity reserved is the value under the Old Value column.

Update myCapacityReservation to the old quantity reserved. After it's updated, the reservation is available immediately for use with your VMs.

Next step

Learn how to remove VMs from a capacity reservation