Modify a Capacity Reservation (preview)

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.

    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.

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:

  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

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.

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

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