Consume reservations

This document explains how to use Compute Engine to do the following:

  • Consume reserved virtual machine (VM) instances.

  • Verify reservations consumption.

  • View reservation usage reports.

For more information about consuming reservations in other Google Cloud products that use VMs, see the reservations documentation for the following products:

Before you begin

  • Review the requirements and restrictions for reservations.
  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to consume reservations, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to consume reservations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to consume reservations:

  • To create reservations: compute.reservations.create on the project
  • To create VMs:
    • compute.instances.create on the project
    • To use a custom image to create the VM: compute.images.useReadOnly on the image
    • To use a snapshot to create the VM: compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM: compute.instanceTemplates.useReadOnly on the instance template
    • To assign a legacy network to the VM: compute.networks.use on the project
    • To specify a static IP address for the VM: compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network: compute.networks.useExternalIp on the project
    • To specify a subnet for the VM: compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM: compute.instances.setMetadata on the project
    • To set tags for the VM: compute.instances.setTags on the VM
    • To set labels for the VM: compute.instances.setLabels on the VM
    • To set a service account for the VM to use: compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM: compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode: compute.disks.use on the disk
    • To attach an existing disk in read-only mode: compute.disks.useReadOnly on the disk
  • To create instance templates: compute.instanceTemplates.create on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Consume reserved VMs

When you create a virtual machine (VM) instance, the VM starts consuming a reservation only if the properties for both the VM and the reservation are matching. Additionally, you must set the reservation affinity property of the VM to one of the following options:

  • Consume any matching reservation—the VM can automatically consume any reservation with matching properties (default).

    This option is useful if you create and delete lots of VMs, and you want to use your reservations whenever possible. In this scenario, a VM can be created whether its properties match a reservation or not. If they match, the VM starts consuming the reservation depending on the reservation's consumption order.

  • Consume a specific reservation—the VM can consume only a specific reservation. The reservation can't be automatically consumed.

    This option is useful when, for example, you want to hold a certain amount of capacity as backup for special events. In this scenario, a VM can be created only if its properties and the specific reservation's properties are matching.

  • Can't consume any reservation at all—the VM can't consume any reservation.

    This option is useful when, for example, you create a temporary VM that you don't want to consume reserved resources.

Consume VMs from any matching reservation

In this consumption model, existing and new VMs automatically consume a reservation if their properties match the VM properties specified in the reservation.

When using this consumption model, the VMs in the current project consume all single-project reservations first before consuming any shared reservations. For more information about how reservations are automatically consumed, see consumption order.

When you create a reservation, this is the default consumption model, as long as you don't use the flag or option that indicates specific reservations are required.

Console

  1. To create a reservation with resources that can be used by VMs with a reservation affinity property configured to consume any reservations (default), follow these steps:

    1. Select the type of reservation that you want to create:

      • To create standalone reservation, do the following:

        1. In the Google Cloud console, go to the Reservations page.

          Go to Reservations

        2. On the On-demand reservation tab (default), click Create reservation.

          The Create a reservation page opens.

      • To create a reservation that is attached to a commitment, do the following:

        1. In the Google Cloud console, go to the Committed use discounts page.

          Go to Committed use discounts

          The Commitment list page opens.

        2. Click Purchase commitment.

          The Purchase a committed use discount page opens.

        3. Specify the commitment properties. Then, in the Reservations section, click Add an item.

          The Add a new reservation section appears.

          For more information about how to purchase a commitment with an attached reservation, see Purchase commitments with attached reservations.

    2. In the Name field, enter a name for your reservation. For this example, enter reservation-01.

    3. Choose the Region and Zone where you want to reserve resources. For this example, select us-central1 as the region and us-central1-a as the zone.

    4. Choose your preferred Share type:

      • To create a reservation for a single project, select Local.
      • To create a shared reservation among multiple projects, select Shared. To share this reservation with other projects, click Add projects and select the desired projects from the current project's organization.

    5. In the Use with VM instance section, select Use reservation automatically, so that any matching VMs can automatically use this reservation.

    6. In the Number of VM instances field, enter the number of VMs that you want to reserve. For this example, enter 2.

    7. Specify the resources that you want to reserve for each VM:

      • If you want to reserve VMs that match an existing instance template, select Use instance template and select an instance template from the list.
      • Otherwise, select Specify machine type and specify the following:
        1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.
        2. Optional: Specify a minimum CPU platform and/or GPUs:
          1. To expand the CPU Platform and GPU section, click the expander arrow.
          2. Optional: To specify a minimum CPU platform, in the CPU Platform list, select an option.
          3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.
        3. Optional: Add local SSDs:
          1. In the Number of disks field, select the number of local SSDs for each VM.
          2. In the Interface type field, select the interface for the local SSDs.

      For this example, select Specify machine type. Then select the n2-standard-32 machine type for the General-purpose machine family and N2 series and select the minimum CPU platform Intel Cascade Lake.

    8. Finish creating the reservation:

      • If you are creating standalone reservation, click Create.

      • If you are creating a reservation that is attached to a commitment:

        1. To finish specifying the properties for this reservation, click Done.
        2. To finish creating the commitment and attached reservations, click Purchase.

  2. In the same project or a project that the reservation is shared with, create a VM that targets any open reservation.

    Ensure that the VM's properties match the VM properties in reservation-01, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    For more information about how to create a VM, see Create and start a VM

    1. In the Google Cloud console, go to the Create an instance page.

      Go to Create an instance

      The Create an instance page opens.

    2. Specify a name for your VM.

    3. In the following sections, select a configuration that exactly matches all the properties of your reservation, including any optional properties. For this example, you must match the following VM properties with reservation-01:

      • Region: us-central1
      • Zone: us-central1-a
      • Machine type: n2-standard-32
      • Minimum CPU platform: Intel Cascade Lake
      • GPUs: none
      • Local SSDs: none

    4. Expand the Advanced options section and then expand the Management section. In the Reservations list, select Automatically use created reservation.

    5. To create the VM, click Create.

gcloud

  1. Create an open reservation called reservation-01.

    gcloud compute reservations create reservation-01 \
    --vm-count=2 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --zone=us-central1-a

  2. Create a VM that targets any open reservation and that matches the VM properties in reservation-01, including the zone, machine type (machine family. vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD amount and interface.

    gcloud compute instances create instance-1 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --zone=us-central1-a \
    --reservation-affinity=any

REST

  1. Create an open reservation named reservation-01.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations

{
  "name": "reservation-01",
  "specificReservation": {
    "count": "2",
    "instanceProperties": {
      "machineType": "n2-standard-32",
      "minCpuPlatform": "Intel Cascade Lake",
    }
  }
}

  2. Create a VM that targets any open reservation and that matches the VM properties in reservation-01, including the zone, machine type (machine family. vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD amount and interface.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances

{
  "name": "instance-1",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "minCpuPlatform": "Intel Cascade Lake",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-12"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "ANY_RESERVATION"
  }
}

Consume VMs from a specific reservation

In this consumption model, only new VMs that target a specific reservation by name can consume that reservation, and the reservation is not consumed automatically.

When creating the reservation, specify that VMs are required to target the specific reservation by using one of the following methods:

  • In the Google Cloud console, select the Select specific reservation checkbox.
  • In the gcloud CLI, include the --require-specific-reservation flag.
  • In the Compute Engine API, set the specificReservationRequired field to true.
  • In Terraform, set the specific_reservation_required field to true.

Then create VMs that specifically target that reservation. You can only create a VM that targets a specific reservation if the VM properties and the reservation's properties are matching. Otherwise, creating the VM fails.

If you are using an instance template to create VMs in a regional managed instance group, create identical reservations with the same name in each applicable zone. Then, target the reservations by name in the group's instance template.

For example, create a specific reservation named reservation-02, and then create a matching VM that targets that reservation and that matches the reservation's VM properties.

Depending on the type of VM you want to consume, follow the steps for Consume a specific single-project reservation or Consume a specific shared reservation.

Consume a specific single-project reservation

To consume a specific single-project reservation, select one of the following options:

Console

  1. To create a reservation with resources that can only be used by VMs that specifically target the reservation by name, follow these steps:

    1. Select one of the following options:

      • To create standalone reservation, do the following:

        1. In the Google Cloud console, go to the Reservations page.

          Go to Reservations

        2. On the On-demand reservations tab (default), click Create reservation.

          The Create a reservation page opens.

      • To create a reservation that is attached to a commitment, do the following:

        1. In the Google Cloud console, go to the Committed use discounts page.

          Go to Committed use discounts

        2. Click Purchase commitment.

          The Purchase a committed use discount page opens.

        3. Specify the commitment properties. Then, in the Reservations section, click Add an item.

          The Add a new reservation section appears.

          For more information about how to purchase a commitment with an attached reservation, see Purchase commitments with attached reservations.

    2. In the Name field, enter a name for your reservation. For this example, enter reservation-02.

    3. Choose the Region and Zone where you want to reserve resources. For this example, select us-central1 as the region and us-central1-a as the zone.

    4. To specify that your reservation will be a single-project reservation, select Local as the Share type.

    5. In the Use with VM instance section, select Select specific reservation, so that only matching VMs that specifically target this reservation by name can use this reservation.

    6. In the Number of VM instances field, enter the number of VMs that you want to reserve. For this example, enter 10.

    7. Specify the resources that you want to reserve for each VM:

      • If you want to reserve VMs that match an existing instance template, select Use instance template and select an instance template from the list.
      • Otherwise, select Specify machine type and specify the following:
        1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.
        2. Optional: Specify a minimum CPU platform and/or GPUs:
          1. To expand the CPU Platform and GPU section, click the expander arrow.
          2. Optional: To specify a minimum CPU platform, in the CPU Platform list, select an option.
          3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.
        3. Optional: Add local SSDs:
          1. In the Number of disks field, select the number of local SSDs for each VM.
          2. In the Interface type field, select the interface for the local SSDs.

      For this example, select Specify machine type. Then select the n2-standard-32 machine type for the General-purpose machine family and N2 series and select the minimum CPU platform Intel Cascade Lake.

    8. Finish creating the reservation:

      • If you are creating standalone reservation, click Create.

      • If you are creating a reservation that is attached to a commitment:

        1. To finish specifying the properties for this reservation, click Done.
        2. To finish creating the commitment and attached reservations, click Purchase.

  2. In the same project, create a VM that targets that specific reservation by name.

    Ensure that the VM's properties match the VM properties of that specific reservation, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    For more information about how to create a VM, see Create and start a VM.

    1. In the Google Cloud console, go to the Create an instance page.

      Go to Create an instance

    2. In the Name field, enter a name for the VM.

    3. In the following sections, select a configuration that exactly matches all the properties of your reservation, including any optional properties. For this example, you must match the following VM properties with reservation-02:

      • Region: us-central1
      • Zone: us-central1-a
      • Machine type: n2-standard-32
      • Minimum CPU platform: Intel Cascade Lake
      • GPUs: none
      • Local SSDs: none

    4. Expand the Advanced options section, and then do the following:

      1. Expand the Management section.

      2. In the Reservations section, in the Application policy list, select Select specific reservation.

      3. Select the reservation with matching VM properties that you want your VM to consume. For this example, select reservation-02.

    5. To create the VM, click Create.

gcloud

  1. Create a reservation named reservation-02 with the --require-specific-reservation flag. These reserved resources can be used only by VMs that specifically target this reservation by name.

    gcloud compute reservations create reservation-02 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --vm-count=10 \
    --zone=us-central1-a \
    --require-specific-reservation

  2. Create a VM that targets reservation-02 by name by using the --reservation-affinity and --reservation flags.

    Ensure that the VM's properties match the reservation's VM properties, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    gcloud compute instances create instance-2 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --zone=us-central1-a \
    --reservation-affinity=specific \
    --reservation=reservation-02

REST

  1. Create a reservation named reservation-02 with the specificReservationRequired field set to true.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations

{
  "name":"reservation-02",
  "specificReservation":{
    "count":"10",
    "instanceProperties":{
      "machineType":"n2-standard-32",
      "minCpuPlatform": "Intel Cascade Lake",
    }
  },
  "specificReservationRequired": true
}

  2. Create a VM that targets reservation-02 by name by using the reservationAffinity field.

    Ensure that the VM's properties match the reservation's VM properties, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances

{
  "name": "instance-2",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "minCpuPlatform": "Intel Cascade Lake",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-clouid/global/images/family/debian-12"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "SPECIFIC_RESERVATION",
    "key": "compute.googleapis.com/reservation-name",
    "values": [
      "reservation-02"
    ]
  }
}

Consume a specific shared reservation

To consume a specific shared reservation, select one of the following options:

Console

  1. To create a shared reservation with resources that can only be used by VMs that specifically target this reservation by name, follow these steps:

    1. Select one of the following options:

      • To create standalone reservation, do the following:

        1. In the Google Cloud console, go to the Reservations page.

          Go to Reservations

        2. On the On-demand reservations tab (default), click Create reservation.

          The Create a reservation page opens.

      • To create a reservation that is attached to a commitment, do the following:

        1. In the Google Cloud console, go to the Committed use discounts page.

          Go to Committed use discounts

        2. Click Purchase commitment.

          The Purchase a committed use discount page opens.

        3. Specify the commitment properties. Then, in the Reservations section, click Add an item.

          The Add a new reservation section appears.

          For more information about how to purchase a commitment with an attached reservation, see Purchase commitments with attached reservations.

    2. In the Name field, enter a name for your reservation. For this example, enter reservation-02.

    3. Choose the Region and Zone where you want to reserve resources. For this example, select us-central1 as the region and us-central1-a as the zone.

    4. To specify that your reservation is a shared reservation, select Shared as the Share type.

    5. Click Add projects and select the projects from the current project's organization that you want to share the reservation with.

    6. In the Use with VM instance section, select Select specific reservation, so that only matching VMs that specifically target this reservation by name can use this reservation.

    7. In the Number of VM instances field, enter the number of VMs that you want to reserve. For this example, enter 10.

    8. Specify the resources that you want to reserve for each VM:

      • If you want to reserve VMs that match an existing instance template, select Use instance template and select an instance template from the list.
      • Otherwise, select Specify machine type and specify the following:
        1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.
        2. Optional: Specify a minimum CPU platform and/or GPUs:
          1. To expand the CPU Platform and GPU section, click the expander arrow.
          2. Optional: To specify a minimum CPU platform, in the CPU Platform list, select an option.
          3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.
        3. Optional: Add local SSDs:
          1. In the Number of disks field, select the number of local SSDs for each VM.
          2. In the Interface type field, select the interface for the local SSDs.

      For this example, select Specify machine type. Then select the n2-standard-32 machine type for the General-purpose machine family and N2 series and select the minimum CPU platform Intel Cascade Lake. 1. Finish creating the reservation:

      • If you are creating standalone reservation, click Create.

      • If you are creating a reservation that is attached to a commitment:

        1. To finish specifying the properties for this reservation, click Done.
        2. To finish creating the commitment and attached reservations, click Purchase.

  2. In the same project or a project that the reservation is shared with, create a VM that targets that specific reservation by name.

    Ensure that the VM's properties match the VM properties of that specific reservation, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    1. In the Google Cloud console, go to the Create an instance page.

      Go to Create an instance

      The Create an instance page opens.

    2. Specify a Name for your VM.

    3. In the following sections, select a configuration that exactly matches all the properties of your reservation, including any optional properties. For this example, you must match the following VM properties with reservation-02:

      • Region: us-central1
      • Zone: us-central1-a
      • Machine type: n2-standard-32
      • Minimum CPU platform: Intel Cascade Lake
      • GPUs: none
      • Local SSDs: none

    4. Expand the Advanced options section and then expand the Management section. In the Reservations list, select Select specific reservation, and then do the following:

      1. Select a Reservation project that has reservations shared with your current project. For this example, select the project that you used to create reservation-02.
      2. Select the Reservation name of the shared reservation that you want this VM to consume. For this example, select reservation-02.

    5. To create the VM, click Create.

gcloud

  1. Create a reservation named reservation-02 with the --require-specific-reservation flag. These reserved resources can be used only by VMs that specifically target this reservation by name.

    gcloud compute reservations create reservation-02 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --vm-count=10 \
    --zone=us-central1-a \
    --project=my-owner-project \
    --share-setting=projects \
    --share-with=project-1,project-2 \
    --require-specific-reservation

  2. Create a VM that targets reservation-02 by name by using the --reservation-affinity and --reservation flags. To consume this reservation from any consumer projects that this reservation is shared with, you must also specify the project that created the reservation, my-owner-project.

    Ensure that the VM's properties match the reservation's VM properties, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    gcloud compute instances create instance-2 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --zone=us-central1-a \
    --reservation-affinity=specific \
    --reservation=projects/my-owner-project/reservations/reservation-02

REST

  1. Create a reservation named reservation-02 with the specificReservationRequired field set to true.

    POST https://compute.googleapis.com/compute/v1/projects/my-owner-project/zones/us-central1-a/reservations

{
  "name":"reservation-02",
  "specificReservation":{
    "count":"10",
    "instanceProperties":{
      "machineType":"n2-standard-32",
      "minCpuPlatform": "Intel Cascade Lake"
    }
  },
  "shareSettings": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "project-1": {
        "projectId": "project-1"
      },
      "project-2": {
        "projectId": "project-2"
      }
    }
  },
  "specificReservationRequired": true
}

  2. Create a VM that targets reservation-02 by name by using the reservationAffinity field. To consume this reservation from any consumer projects that this reservation is shared with, you must also specify the owner project of the reservation, my-owner-project.

    Ensure that the VM's properties match the reservation's VM properties, including the zone, machine type (machine family, vCPUs, and memory), minimum CPU platform, GPU amount and type, and local SSD interface and size.

    POST https://compute.googleapis.com/compute/v1/projects/project-2/zones/us-central1-a/instances

{
  "name": "instance-2",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "minCpuPlatform": "Intel Cascade Lake",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-clouid/global/images/family/debian-12"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "SPECIFIC_RESERVATION",
    "key": "compute.googleapis.com/reservation-name",
    "values": [
      "projects/my-owner-project/reservations/reservation-02"
    ]
  }
}

Create VMs without consuming reservations

If you create an automatically consumed reservation, then any running VMs with matching properties in your project can consume the reservation. To prevent one or more of your VMs from consuming the reservation, do the following:

  • Set the reservation affinity property of the VMs to explicitly not consume any reservations as described in this section.

  • Make sure that your VMs don't match the VM properties of the reservation.

To create VMs that explicitly don't consume reservations, select one of the following methods:

Create a VM to not consume reservations

To create a VM that explicitly doesn't consume reservations, select one of the following options:

Console

  1. In the Google Cloud console, go to the Create an instance page.

    Go to Create an instance

  2. In the Name field, enter a name for the VM.

  3. In the Region and Zone lists, select the region and zone in which to create the VM.

  4. In the Machine configuration section, specify the machine type to use for the VM.

  5. Expand the Advanced options section, and then do the following:

    1. Expand the Management section.

    2. In the Reservations section, in the Application policy list, select Don't use.

  6. Click Create.

gcloud

To create a VM that explicitly doesn't consume reservations, use the gcloud compute instances create command with the --reservation-affinity=none flag.

gcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --reservation-affinity=none \
    --zone=ZONE

Replace the following:

  • VM_NAME: the name of the VM.

  • MACHINE_TYPE: the machine type to use for the VM.

  • ZONE: the zone in which to create the VM.

REST

To create a VM that explicitly doesn't consume reservations, make a POST request to the instances.insert method. In the request body, include the consumeReservationType field set to NO_RESERVATION.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "NO_RESERVATION"
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project in which to create the VM.

  • ZONE: the zone in which to create the VM.

  • VM_NAME: the name of the VM.

  • MACHINE_TYPE: the machine type to use for the VM.

  • IMAGE_PROJECT: the image project that contains the OS image—for example, debian-cloud. For more information about the supported image projects, see Public images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example, debian-12-bookworm-v20240617.

    • An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

For more information about creating a VM, see Create and start a Compute Engine instance.

Create an instance template to not consume reservations

To create an instance template that creates VMs that don't explicitly consume reservations, select one of the following options:

Console

  1. In the Google Cloud console, go to the Create an instance template page.

    Go to Create an instance template

  2. In the Name field, enter a name for the instance template.

  3. In the Location section, specify whether you want to create a regional (default) or global instance template.

  4. In the Machine configuration section, specify the machine type to use for the VMs created using the template.

  5. Expand the Advanced options section, and then do the following:

    1. Expand the Management section.

    2. In the Reservations section, in the Application policy list, select Don't use.

  6. Click Create.

gcloud

To create an instance template that creates VMs that don't explicitly consume reservations, use the gcloud compute instances-templates create command with the --reservation-affinity=none flag.

For example, to create a global instance template that creates VMs that don't explicitly consume reservations, run the following command:

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=MACHINE_TYPE \
    --reservation-affinity=none

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.

  • MACHINE_TYPE: the machine type to use for the VMs created using the instance template.

REST

To create an instance template that creates VMs that don't explicitly consume reservations, make a POST request to one of the following methods:

In the request body, include the consumeReservationType field and set it to NO_RESERVATION.

For example, to create a global instance template that creates VMs that don't explicitly consume reservations, make a request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/InstanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "machineType": "MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "reservationAffinity": {
      "consumeReservationType": "NO_RESERVATION"
    }
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project in which to create the instance template.

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.

  • MACHINE_TYPE: the machine type to use for the VMs created using the instance template.

  • IMAGE_PROJECT: the image project that contains the OS image—for example, debian-cloud. For more information about the supported image projects, see Public images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example, debian-12-bookworm-v20240617.

    • An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

For more information about creating instance templates, see Create instance templates.

Test that VM properties match a reservation

To test whether VMs can automatically consume a reservation, you can create a copy of the reservation as a specific reservation, and then see if a VM you plan to create can consume that reservation. If you can successfully create the VM, then you've verified that the VM can correctly consume the matching reservation. Otherwise, creating the VM fails because the properties don't match or there are no available reserved resources. After testing, you can do one or more of the following:

Verify reservations consumption

To ensure that your VMs are effectively consuming your reservations, you can verify their consumption using the following methods:

  • View the details of the reservation

    If the number of VMs consuming a reservation increases by 1 after you create or update a VM, then your action likely caused the VM to start consuming the reservation. This is the quickest way to check if a reservation is being consumed. However, it might not work well to verify which exact VM is consuming the reservation.

  • Create the VM to target a specific reservation

    If you can successfully create a VM that targets a specific reservation, then the VM is consuming the reservation. This is the most reliable method to verify that a specific VM is consuming a reservation and that the VM's properties match the reservation's properties.

  • Monitor your reservations consumption

    By using Cloud Monitoring, you can access and view the information associated with the consumption of the reservations that were created in your project. Monitoring updates you reservations consumption data at least once every 30 minutes. This method is useful to verify the consumption trend of one or more reservations in a project, as well as receive notifications for underused or unused reservations.

  • View the historical usage of your reservations

    By using Capacity Planner (Preview), you can access and view the historical usage of your reservations from their creation up to their deletion. Capacity Planner updates reservations consumption data every 24 hours. This method is useful for verifying the past consumption of your reservations within a project, folder, or organization, as well as helping you plan for future capacity needs.

If you see that a VM isn't consuming a reservation after you've verified that the VM's reservation affinity can consume the reservation, the reservation isn't fully consumed, and the VM and the reservation's properties are matching, then see Resource availability.

View reservation usage reports

Export detailed reports of your Compute Engine usage to a Cloud Storage bucket using the usage export feature. For instructions, see Viewing usage reports.

The usage report shows the following:

  • The reserved resources that are in use. These entries appear as normal vCPU, memory, GPU, and local SSD resources.
  • The reserved resources that are not in use. These entries have normal SKU names and reservation resource URIs.
  • Total reserved resources. These entries have reservation SKU names and reservation resource URIs. There are no costs associated with these entries. Use these entries to calculate how much of your reservations you are using.
Measurement MeasurementId format Resource URI format
Reserved resources that are in use com.google.cloud/services/compute-engine/SKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/RESOURCE_NAME.

For example, https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/my-instance
Reserved resources that are not in use com.google.cloud/services/compute-engine/SKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME.

For example, https://compute.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-b/reservations/my-reservation
Total reserved resources com.google.cloud/services/compute-engine/ReservationSKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME.

For example, https://compute.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-b/reservations/my-reservation

For example, in the following snippet from a usage report for a reservation named my-reservation:

  • Row 1 shows reserved RAM that is currently in use. The row's ResourceId shows that this RAM is used by a VM named my-instance.
  • Row 2 shows reserved RAM that is not in use. The row's ResourceId shows that this reserved RAM is held by my-reservation; it is not yet used by any VM.
  • Row 3 shows the reservation's total reserved RAM.
Report Date,MeasurementId,Quantity,Unit,Resource URI,ResourceId,Location
2019-06-06,com.google.cloud/services/compute-engine/VmimageN2StandardRam,166970074857472,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/instances/my-instance,1775485842510981624,us-central2-a
2019-06-06,com.google.cloud/services/compute-engine/VmimageN2StandardRam,166970074857472,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/reservations/my-reservation,7.58809E+17,us-central2-a
2019-06-06,com.google.cloud/services/compute-engine/ReservationN2StandardRam,333940149714944,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/reservations/my-reservation,7.58809E+17,us-central2-a
...

Troubleshoot

Learn how to troubleshoot issues with reservation consumption.

What's next