Troubleshooting reservation consumption

This page shows you how to resolve issues with consuming reservations of Compute Engine zonal resources.

Difficulty tracking reservation consumption

Issue: Although you can describe a reservation to view how many of its reserved VMs are being consumed and monitor changes to this number over time, you cannot directly view which VMs are consuming a reservation.

Resolution: You can help mitigate this limitation by doing the following:

If you need to track which VMs are consuming which reservation, use specific reservations. For a specific reservation, you can identify which VMs are consuming that reservation by looking for the reservation affinity (reservationAffinity) property in your VMs. For details, see Consuming VMs from a specific reservation.
Use reservations that are consumed automatically (default) only when you do not have any preferences about which VMs consume a reservation.

Issues for VMs not consuming reservations

If a VM can't consume a reservation, it might be due to one or more of the following issues:

The VM's properties don't match the reservation's properties.
The VM's reservation affinity is incorrect.
The reservation is already fully consumed by other matching VMs.

This section describes how to identify each of these issues, how to resolve each, and how to verify reservation consumption.

Mismatched VM properties

Issue: A VM cannot consume a reservation with different VM properties.

To identify this issue, select one of the following methods:

Describe the reservation and VM, and manually verify that their VM properties match:
1. Describe the reservation that you want the VM to consume using the gcloud compute reservations describe command:
```
gcloud compute reservations describe RESERVATION_NAME --zone=ZONE
```
  Replace the following:
  - RESERVATION_NAME is the name of a reservation.
  - ZONE is the zone where the reservation is located.
  Keep this output available.
2. Describe the VM that you want to consume the reservation gcloud compute instances describe command.
```
gcloud compute instances describe VM_NAME
```
  where VM_NAME is the name of the VM.
  
  Keep this output available.
3. Using both the VM description and reservation description outputs, verify that following properties match:
  - project
    - If the reservation is shared with multiple projects (if the reservation has theshareType property set to SPECIFIC_PROJECTS), the VM's project can either match the project where the reservation is located or match any of the projects listed under shareSettings.
  - zone
  - machineType
  - guestAccelerators.acceleratorType
  - guestAccelerators.acceleratorCount
  - minCpuPlatform
    - If your reservation or VM has a minCpuPlatform property, the VM or reservation must also have the same minCpuPlatform property. Otherwise, both the reservation and the VM should omit the minCpuPlatform property.
  - localSsds.interface
    - The reservation and VM must have the same number of local SSDs with a matching localSsds.interface property for each local SSD.
  - resourcePolicies^*
  ^*Only if a reservation specifies a compact placement policy.
Create a VM that targets a specific reservation, which returns an error if the properties don't match. For instructions, see Verify reservation consumption.

Resolution: Update any mismatched VM properties by doing one of the following:

Update the VM to match the reservation's properties.
Delete the reservation and create a new reservation that matches the VM's properties.

To check if the VM is now consuming the reservation, see Verify reservation consumption.

If the VM's and reservation's properties match but the VM is not consuming the reservation, proceed to the next section.

VMs miss a placement policy

Issue: A VM is trying to consume a reservation without specifying the reservation's compact placement policy.

Resolution: If a single-project reservation specifies a compact placement policy, a VM must specify exactly the same compact placement policy to consume the reservation. Otherwise, the VM can't consume the reservation.

To make sure that a VM consumes a reservation that specifies a compact placement policy, try one of the following:

If you created a single-project reservation by specifying properties directly, apply the compact placement policy when creating VMs.
If you created a single-project reservation by specifying an instance template, select one of the following methods:
- Recommended: use the reservation's instance template to create VMs. This action automatically applies the same compact placement policy specified in the reservation to each new VM you create.
- Apply the compact placement policy when creating VMs. This method requires you to manually ensure that the compact placement policy, and any other VM properties, of your VMs and reservations match exactly—any mismatched properties prevent consumption.

VMs specify a different compact placement policy

Issue: A VM is trying to consume a reservation, but the compact placement policy specified in the VM and in the reservation don't match.

To solve this issue, try one of the following:

If you created a single-project reservation by specifying properties directly, apply the reservation's compact placement policy when creating new VMs.
If you created a single-project reservation by specifying an instance template, use the same template to create VMs. This action automatically applies the same compact placement policy specified in the reservation to each new VM you create.

VM's reservation affinity is incorrect

Issue: The VM's reservation affinity is misconfigured. A VM's reservation affinity controls the reservations that a VM can consume. To check your VM's reservation affinity, do the following:

Describe the reservation that you want the VM to consume with the gcloud compute reservations describecommand.
```
  gcloud compute reservations describe RESERVATION_NAME --zone=ZONE
```
Replace the following:
- RESERVATION_NAME is the name of a reservation.
- ZONE is the zone where the reservation is located.
In the output, find the value of the specificReservationRequired field, either true or false.

Describe the VM using the gcloud compute instances describecommand.

   gcloud compute instances describe VM_NAME

where VM_NAME with the name of the VM.

In the output, find the reservationAffinity field, which looks similar to the following:

...
   reservationAffinity:
     consumeReservationType: RESERVATION_AFFINITY
     key: compute.googleapis.com/reservation-name
     values:
     - RESERVATION_NAME
   ...

Resolution: Update the VM's reservationAffinity property to be compatible with the reservation's specificReservationRequired field by using one of the following accepted configurations:

If the reservation's specificReservationRequired field is true, the VM's reservationAffinity property must match the following:
```
...
  reservationAffinity:
    consumeReservationType: SPECIFIC_RESERVATION
    key: compute.googleapis.com/reservation-name
    values:
    - RESERVATION_NAME
  ...
```
where RESERVATION_NAME is the name of the reservation.
If the reservation's specificReservationRequired field is false, the VM's reservationAffinity property must match the following:
```
...
  reservationAffinity:
    consumeReservationType: ANY_RESERVATION
  ...
```

You need to restart the VM to make the update. After the update, to check if the VM is consuming the reservation, see Verify reservation consumption.

If the VM's reservation affinity is configured correctly but the VM is not consuming any reservations, proceed to the next section.

Reservation is already fully consumed

Issue: The number of VMs currently in use for this reservation matches the reservation's total number of reserved VMs.

To identify this issue, describe the reservation and and verify that the number of VMs currently in use for this reservation is less than the reservation's total number of reserved VMs.

Resolution: You can increase the number of VMs available to consume for the reservation by doing one of the following:

Increase the number of VMs in the reservation by resizing the reservation.
Create a new reservation with the same properties, if the reservation already reserves the maximum number of VMs.
Reduce the number of other VMs that are consuming the reservation. For more information, see VMs unintentionally consuming reservations.

To check if the VM is now consuming the reservation, see Verify reservation consumption.

If the reservation is not fully consumed, but the VM is not consuming the reservation, you can further troubleshoot the issue by creating a VM that targets a specific reservation, which returns an error if the consumption fails. For more information, proceed to the next section.

Verify reservation consumption

A simple method to verify if a VM is consuming a reservation is to describe the reservation before and after you create or update a VM. If the reservation's VMs in use increases by 1 after your change, your change probably caused that VM to start consuming this reservation. However, this method might not work well in complex situations, such as if the VM can consume multiple reservations or if you need to troubleshoot.

Alternatively, if you want a reliable way to verify only if a VM can consume a reservation, create a VM that targets a specific reservation. If you attempt to create a VM that targets a specific reservation, the VM cannot be created and returns an error unless it can consume the targeted reservation. Even if you want to use a reservation that is automatically consumed, you can use still use this method as preliminary test to verify that a VM is configured correctly for reservation consumption.

Create a reservation that requires VMs to specifically target it. If you are creating a new reservation for testing purposes only, make sure the new reservation's VM properties exactly match the existing reservation that you want the VM to consume.
Create a VM that explicitly matches the reservation's VM properties and that targets the specifically consumed reservation by name through the VM's reservation affinity property.
- If you see an error, try to resolve it. For example, if either the VM or reservation are not configured correctly, you might see an error related to mismatched VM properties or not targeting a reservation correctly.
- If you can create a VM that targets the reservation successfully, you have verified that the properties of your VM and reservation match. To clean up, delete or update the reservation and delete or update the VM as needed; delete any test resources that you no longer need or update the resources if you want them to have a different reservation affinity.

If a VM still cannot consume a reservation after you have verified the VM's reservation affinity, the reservation's capacity, and both resources' VM properties, then the error might be caused by resource availability. Otherwise, if you were unable to resolve the issue using any of the preceding instructions, try Getting support.

VMs unintentionally consuming reservations

Issue: When you create reservations that are consumed automatically (default), VMs might unintentionally consume these reservations.

Resolution: You can help control which VMs consume reservations by doing the following:

Use VMs that cannot consume any reservations where desired.
Use reservations that are only consumed when specifically targeted instead of automatically consumed reservations.