Modify a Capacity Reservation

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

After creating a Capacity Reservation group and Capacity Reservation, you may want to modify your reservations. This article explains how to do the following actions using API, Azure portal, and PowerShell.

• Update the number of instances reserved in a Capacity Reservation
• Resize VMs associated with a Capacity Reservation group
• Delete the Capacity Reservation group and Capacity Reservation

Update the number of instances reserved

Update the number of virtual machine instances reserved in a Capacity Reservation.

Important

In rare cases when Azure cannot fulfill the request to increase the quantity reserved for existing Capacity Reservations, it is possible that a reservation goes into a Failed state and becomes 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
    }
} 

Note that the capacity property is set to 5 now in this example.

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

In order 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

In order 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, go to Azure PowerShell command Update-AzCapacityReservation.

Resize VMs associated with 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 virtual machine from the reservation group before resizing.

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:

   1. If the target VM size is not 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 virtual machine

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 is not 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 virtual machine

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. Run the following commands to find out the VM size(s) reserved for each reservation

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

4. Consider the following scenarios:

   1. If the target VM size is not 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 virtual machine

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. Run the following commands to find out the VM size(s) reserved for each reservation

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

4. Consider the following scenarios:

   1. If the target VM size is not 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 virtual machine

To learn more, go to 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 have been deleted and no VMs are associated to the group.

To delete a Capacity Reservation, first find out all of the virtual machines that are associated to it. The list of virtual machines is available under virtualMachinesAssociated property.

API

First, find all virtual machines associated with 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 above response, find the names of all virtual machines under the virtualMachinesAssociated property and remove them from the Capacity Reservation group using the steps in Remove a VM association to a Capacity Reservation.

Once all the virtual machines are removed from the Capacity Reservation group, delete the member Capacity Reservation(s):

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 virtual machines that are associated with the group
5. Disassociate every virtual machine
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 virtual machines associated with Capacity Reservation group and dissociate them.

1. Run the following command:

   az capacity reservation group show
   -g myResourceGroup
   -n myCapacityReservationGroup
   

2. From the above response, find out the names of all the virtual machines under the VirtualMachinesAssociated property and remove them from the Capacity Reservation group using the steps detailed in Remove a virtual machine association from a Capacity Reservation group.

3. Once all the virtual machines are removed from the group, proceed to the next steps.

4. Delete the Capacity Reservation:

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

5. Delete the Capacity Reservation group:

   az capacity reservation group delete 
   -g myResourceGroup 
   -n myCapacityReservationGroup
   

PowerShell

Find out all the virtual machines associated with Capacity Reservation group and dissociate them.

1. Run the following command:

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

2. From the above response, find out the names of all the virtual machines under the VirtualMachinesAssociated property and remove them from the Capacity Reservation group using the steps detailed in Remove a virtual machine association from a Capacity Reservation group.

3. Once all the virtual machines are removed from the group, proceed to the next steps.

4. Delete the Capacity Reservation:

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

5. Delete the Capacity Reservation group:

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

To learn more, go to Azure PowerShell commands Get-AzCapacityReservationGroup, Remove-AzCapacityReservation, and Remove-AzCapacityReservationGroup.

Restore instance quantity

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

Note

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

For example, let’s say myCapacityReservation has a quantity reserved 5. You request 5 extra instances, making the total quantity reserved equal 10. However, because of a constrained capacity situation in the region, Azure can’t fulfill the additional 5 quantity requested. In this case, myCapacityReservation will fail to meet its intended state of 10 quantity reserved and will go into a Failed state.

To resolve this failure, take the following steps to locate the old quantity reserved value:

1. Go to Application Change Analysis in the Azure portal
2. Select the applicable Subscription, Resource group, and Time range 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 sku.capacity property for that reservation
   • The old quantity reserved will be the value under the Old Value column

Update myCapacityReservation to the old quantity reserved. Once updated, the reservation will be available immediately for use with your virtual machines.

Next steps

Learn how to remove VMs from a Capacity Reservation