Consume and manage Compute Engine zonal reservations

Stay organized with collections Save and categorize content based on your preferences.

This document explains how to consume and manage reservations for Compute Engine zonal resources. For more information about reservations, see the following:

Before you begin

Consume reserved instances

When you create a virtual machine (VM) instance, set the instance's reservation affinity property to choose if the instance can use any available matching reservation (default), use a specific reservation, or use no reservation at all. The reservation affinity property appears as the following:

  • Use with VM instance section in Google Cloud console
  • --reservation-affinity flag in gcloud CLI
  • "reservationAffinity" field in the Compute Engine API

In all cases, a VM can only consume a reservation if the properties for both the VM and reservation are matching.

For an instance to consume from a specific reservation, that reservation must be created with the corresponding specific reservation required property.

For more information, see How reservations work.

Consume instances from any matching reservation

In this consumption model, existing and new instances automatically count against the reservation if those instances' properties match the reserved instance's properties. This model is useful if you create and delete lots of VMs and you want to use the reservations whenever possible.

When using this consumption model, all single-project reservations are consumed before any shared reservations, since the latter are more widely available. For more information about how instances are automatically consumed, see consumption order.

To use this model, exclude the --require-specific-reservation flag when creating your reservations, so that matching instances can consume from these reservations automatically.

Console

  1. To create a reservation with resources that can be used by VM instances 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

          The Reservations page appears.

        2. Click Create reservation.

          The Create a reservation page appears.

      • 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 appears.

        2. Click Purchase commitment.

          The Purchase a committed use discount page appears.

        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 Attach reservations to commitments in this document.

    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 VM instances can automatically use this reservation.

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

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

      • 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 instance that targets any open reservation.

    Ensure that the VM instance's properties match the VM instance 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 instance, see Creating and starting a VM instance

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

      Go to Create an instance

      The Create an instance page appears.

    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 instance 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 Networking, disks, security, management, sole tenancy 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 instance that targets any open reservation and that matches the instance 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

API

  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",
    }
  },
  "specificReservationRequired": false
}

  2. Create a VM instance that targets any open reservation and that matches the instance 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",
  "reservationAffinity":
  {
    "consumeReservationType": "ANY_RESERVATION"
  },
  ...
}

Consume instances from a specific reservation

In this consumption model, only new instances that target a specific reservation by name consume that reservation, and the reservation is not consumed automatically. This model is useful, for example, when you want to hold a certain amount of capacity as backup for special events.

When creating the reservation, specify that instances 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.

Then create VMs that specifically target that reservation and that match its properties.

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 instance that targets that reservation and that matches the reservation's instance properties.

Depending on the type of instance 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, use the Google Cloud console, gcloud CLI, or Compute Engine API.

Console

  1. To create a reservation with resources that can only be used by VM instances 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

          The Reservations page appears.

        2. Click Create reservation.

          The Create a reservation page appears.

      • 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 appears.

        2. Click Purchase commitment.

          The Purchase a committed use discount page appears.

        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 and combine it with a reservation, see Attach reservations to commitments in this document.

    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 VM instances that specifically target this reservation by name can use this reservation.

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

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

      • 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 instance that targets that specific reservation by name.

    Ensure that the VM instance's properties match the VM instance 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 instance, see Creating and starting a VM instance.

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

      Go to Create an instance

      The Create an instance page appears.

    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 instance 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 Networking, disks, security, management, sole tenancy section and then expand the Management section. In the Reservations list, select Select specific reservation, and then select the Reservation name with matching properties that you want your instance 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 instances 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 instance that targets reservation-02 by name by using the --reservation-affinity and --reservation flags.

    Ensure that the instance's properties match the reservation's instance 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

API

  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 instance that targets reservation-02 by name by using the reservationAffinity field.

    Ensure that the instance's properties match the reservation's instance 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",
  "reservationAffinity":
  {
    "consumeReservationType": "SPECIFIC_RESERVATION",
    "key": "compute.googleapis.com/reservation-name",
    "values":
    [
      "reservations/reservation-02"
    ]
  },
  ...
}

Consume a specific shared reservation

To consume a specific shared reservation, use the Google Cloud console, gcloud CLI, or Compute Engine API.

Console

  1. To create a shared reservation with resources that can only be used by VM instances 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

          The Reservations page appears.

        2. Click Create reservation.

          The Create a reservation page appears.

      • 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 appears.

        2. Click Purchase commitment.

          The Purchase a committed use discount page appears.

        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 and combine it with a reservation, see Attach reservations to commitments in this document.

    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 VM instances that specifically target this reservation by name can use this reservation.

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

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

      • 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 instance that targets that specific reservation by name.

    Ensure that the VM instance's properties match the VM instance 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 appears.

    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 instance 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 Networking, disks, security, management, sole tenancy 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 instance 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 instances 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 instance 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 instance's properties match the reservation's instance 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

API

  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 instance 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 project that created the reservation, my-owner-project.

    Ensure that the instance's properties match the reservation's instance 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",
  "reservationAffinity":
  {
    "consumeReservationType": "SPECIFIC_RESERVATION",
    "key": "compute.googleapis.com/reservation-name",
    "values":
    [
      "projects/my-owner-project/reservations/reservation-02"
    ]
  },
  ...
}

Create instances without consuming reservations

To explicitly avoid consuming resources from any reservation, set the reservation affinity property to not use any reservations when creating the VM. Or, to implicitly avoid using up any of your reservations, create an instance that doesn't match the instance properties of any of your reservations.

Console

  1. Create a VM that explicitly doesn't consume from a reservation.

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

      Go to Create an instance

    2. Create a VM. For more information, see Creating and starting a VM instance.

    3. Expand the Networking, disks, security, management, sole tenancy section, and then do the following:

      1. Expand the Management section.
      2. To ensure that this VM doesn't consume from existing reservations, in the Reservations list, select Don't use.

    4. Click Create.

gcloud

Create an instance that explicitly does not consume from a reservation.

gcloud compute instances create instance-3 --reservation-affinity=none

Or create an instance that does not match the instance properties in any of your reservations. To review your reservation properties, see list and describe reservations.

API

Create an instance that explicitly does not consume from a reservation.

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

{
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "name": "instance-3",
  "reservationAffinity":
  {
    "consumeReservationType": "NO_RESERVATION"
  },
  ...
}

Or create an instance that does not match the instance properties in any of your reservations. To review your reservation properties, see list and describe reservations.

Troubleshoot reservation consumption

Learn how to verify reservation consumption and troubleshoot issues with reservation consumption.

List and describe reservations

You can only list and describe reservations that were created by your current project. Consequently, shared reservations are only listed for the owner project—you cannot list the reservations shared with a project or list all the reservations in an organization. You can also view the list of all the consumer projects for a shared reservation when you describe that reservation. For recommendations about how to manage shared reservations, see best practices for shared reservations.

List reservations

To view a list of your reservations created by your current project, you can use the Google Cloud console, gcloud CLI, or Compute Engine API.

Console

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

Go to Reservations

The Reservations page appears.

In the table, each row describes a reservation and each column describes a property. For example, the Used machines column describes the utilization and total capacity of each reservation: a value of 25 (50) represents a reservation for 50 instances, and 25 of these instances have been consumed and are currently in use.

Optional: To modify which reservations and properties are displayed, use Filter and Column display options respectively.

gcloud

To view a list of your reservations, use the gcloud compute reservations list command:

gcloud compute reservations list

The output should be similar to the following example:

NAME             IN_USE_COUNT   COUNT   ZONE
reservation-04   25             50      us-central1-a
reservation-05   0              100     us-central1-b

If you want to narrow the list of your reservations to a specific zone or to the reservations created using an instance template, specify the following --filter flags:

gcloud compute reservations list \
    --filter="specificReservation.sourceInstanceTemplate=https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates/INSTANCE_TEMPLATE_NAME" \
    --filter="zone=ZONE"

Replace the following:

  • PROJECT_ID: the project ID of the project that you used to create your reservations.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template that you used to create your reservations.

  • ZONE: a zone where you reserved resources.

API

To list your reservations, make a GET request to the reservations.list method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

Replace the following:

  • PROJECT_ID: the project ID of the project that you used to create your reservations.
  • ZONE: the zone where the reservations are located.

The output should be similar to the following example:

{
  "id": "4100668622331754141",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-05",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-05",
    "count": "100",
    "inUseCount": "0"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation"
},
{
  "id": "2533514314332214789",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-04",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "guestAccelerators": [
        {
          "acceleratorType": "nvidia-tesla-k80",
          "acceleratorCount": 1
        }
      ],
      "minCpuPlatform": "Any CPU Platform",
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation"
}

Describe reservations

To describe a reservation created by your current project, you can use the Google Cloud console, gcloud CLI, or Compute Engine API.

Console

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

    Go to Reservations

    The Reservations page appears.

  2. In the Name column, click the name of the reservation you want to describe.

    The details page for the reservation appears.

gcloud

To describe a reservation, use the gcloud compute reservations describe command:

gcloud compute reservations describe RESERVATION_NAME \
    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of an existing reservation.
  • ZONE: the zone where the reservation is located.

The output should be similar to the following example:

kind: compute#reservation
name: reservation-04
selfLink: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04
specificReservation:
  count: '50'
  inUseCount: '25'
  instanceProperties:
    guestAccelerators:
    - acceleratorCount: 1
      acceleratorType: nvidia-tesla-k80
    localSsds:
    - diskSizeGb: '375'
      interface: SCSI
    machineType: n1-standard-2
    minCpuPlatform: Any CPU Platform
specificReservationRequired: false
status: READY
zone: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

You can use the count and inUseCount values to determine the utilization of each reservation. In this example, 50 instances are reserved for reservation-04, and 25 of these instances have been consumed from the reservation and are currently in use.

To create an instance that uses this reservation, remember to match the reservation's instance properties. For example:

gcloud compute instances create my-instance \
    --accelerator=type=nvidia-tesla-k80,count=1 \
    --local-ssd=size=375,interface=scsi \
    --machine-type n1-standard-2 \
    --zone us-central1-a

API

To describe a reservation, call the reservations.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME

Replace the following:

  • PROJECT_ID: the project ID of the project that you used to create the reservation.
  • ZONE: the zone where the reservation is located.
  • RESERVATION_NAME: the name of an existing reservation.

The output should be similar to the following example:

{
  "id": "2533514314332214789",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-centra1-a",
  "name": "reservation-04",
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "guestAccelerators": [
        {
          "acceleratorType": "nvidia-tesla-k80",
          "acceleratorCount": 1
        }
      ],
      "minCpuPlatform": "Any CPU Platform",
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25"
  }
}

You can use the count and inUseCount values to determine the utilization of each reservation. In this example, 50 instances are reserved, and 25 of these instances have been consumed from the reservation and are currently in use.

Modify reservations

If you want to modify a reservation, select one of the following methods:

Resize a reservation

You can resize a reservation to increase (upsize) or decrease (downsize) the number of reserved VMs.

  • If you want to upsize any reservation, the following restrictions apply:

    • There must be sufficient resources in the zone where the reservation is located.

    • You must have sufficient quota for the additional resources you're reserving.

  • If you want to downsize a specific reservation, make sure that the number of VMs in the reservation equals the number of VMs that are targeting the reservation by doing one or more of the following:

To resize the number of VMs in a reservation, use the Google Cloud console, gcloud CLI, or Compute Engine API.

Console

To resize a reservation, follow these steps:

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

    Go to Reservations

    The Reservations page appears.

  2. In the Name column, click the name of the reservation you want to resize.

    The details page for the reservation appears.

  3. Click Edit.

  4. In the Number of VM instances field, enter the updated number of VMs to reserve.

  5. To confirm, click Save.

    Resizing your reservation might take a few seconds to complete.

gcloud

To resize a reservation, use the gcloud compute reservations update command.

gcloud compute reservations update RESERVATION_NAME \
    --vm-count=NUMBER_OF_VMS \
    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of an existing reservation.

  • NUMBER_OF_VMS: the updated number of VMs to reserve.

  • ZONE: the zone where the existing reservation is located.

API

To resize a reservation, make a POST request by using the reservations.resize method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME/resize

{"specificSkuCount": "NUMBER_OF_VMS"}

Replace the following:

  • PROJECT_ID: the project ID of the project that you used to create the reservation.

  • ZONE: the zone where the existing reservation is located.

  • RESERVATION_NAME: the name of an existing reservation.

  • NUMBER_OF_VMS: the updated number of VMs to reserve.

Add or remove consumer projects to a shared reservation

To modify the consumer projects for a shared reservation, use the Google Cloud console, gcloud CLI, or the Compute Engine API. If you want to see the projects that a reservation is shared with, describe the reservation.

Console

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

    Go to Reservations

    The Reservations page appears.

  2. In the Name column, click the name of the reservation you want to describe.

    The details page for the reservation appears.

  3. Click Edit.

  4. In the Selected projects section, do one of the following:

    • To stop sharing the reservation with a specific consumer project, click Delete.

    • To start sharing the reservation with one or more specific projects, click Add projects. In the dialog that appears, select the checkbox for each project from the owner project's organization that you want to share the reservation with. Then, click Select.

  5. To confirm your changes, click Save.

    Modifying your reservation might take a few seconds to complete.

gcloud

Using the gcloud CLI, you can change the list of projects that can consume a shared reservation by adding projects, removing projects, or replacing the entire list.

  • To add one or more projects to the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --add-share-with flag.

    gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --add-share-with=CONSUMER_PROJECT_IDS

    Replace the following:

    • RESERVATION_NAME: the name of the shared reservation that you want to modify.
    • ZONE: the zone where the reservation is located.
    • OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
    • CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of projects that you want to share this reservation with; for example project-1,project-2. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

  • To remove one or more projects to the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --remove-share-with flag.

    gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --remove-share-with=CONSUMER_PROJECT_IDS

    Replace the following:

    • RESERVATION_NAME: the name of the shared reservation that you want to modify.
    • ZONE: the zone where the reservation is located.
    • OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
    • CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of projects that you want to stop sharing this reservation with; for example project-1,project-2. You cannot stop sharing this reservation with the OWNER_PROJECT_ID.

  • To replace the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --share-with flag.

    gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --share-with=CONSUMER_PROJECT_IDS

    Replace the following:

    • RESERVATION_NAME: the name of the shared reservation that you want to modify.
    • ZONE: the zone where the reservation is located.
    • OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
    • CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of all the projects that you want to allow to consume this reservation; for example project-1,project-2. Include any existing consumer project IDs that you want to continue sharing this reservation with, and omit any project IDs that you want to stop sharing this reservation with. Then, add any new consumer project IDs that you also want to share this reservation with. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

API

In the API, construct a PATCH request to the reservations.update method. In the request body, use the shareSettings.projectMap field to replace the list of projects that this reservation is shared with.

PATCH https://compute.googleapis.com/compute/v1/projects/OWNER_PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=sharedSettings.projects

{
  "shareSetting": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "CONSUMER_PROJECT_ID_1": {
        "projectId": "CONSUMER_PROJECT_ID_1"
      },
      "CONSUMER_PROJECT_ID_2": {
        "projectId": "CONSUMER_PROJECT_ID_2"
      }
    }
  }
}

Replace the following:

  • OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
  • ZONE: the zone where the reservation is located.
  • RESERVATION_NAME: the name of the reservation that you want to modify. Currently, this must be a shared reservation.
  • CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the project IDs of one or more projects that you want to share this reservation with. Include any existing consumer project IDs that you want to continue sharing this reservation with, and omit any project IDs that you want to stop sharing this reservation with. Then, add any new consumer project IDs that you also want to share this reservation with. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

After you modify which projects can consume a reservation, the consumption of the reservation might change. For example, any removed consumer projects stop consuming resources from this reservation. Additionally, if this reservation was configured to be automatically applied to any new or existing instances that match the reservation's properties (the default behavior), any added consumer projects might start consuming resources from this reservation. If you want to monitor this reservation's consumption, see List and describe reservations.

Change other properties in a reservation

If you want to modify a reservation that is attached to a commitment, see instead Replace reservations that are attached to commitments in this document.

To change any other properties of a reservation, do the following:

  1. Create a new reservation with the desired updates.

  2. Delete the older reservation.

Troubleshoot reservation updates

Learn how to troubleshoot issues with reservation updates.

Delete a reservation

You can delete reservations that aren't tied to a commitment by using the console, the gcloud CLI, or the API.

Console

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

    Go to Reservations

    The Reservations page appears.

  2. Select the checkbox next to each reservation that you want to delete.

  3. Click Delete reservation.

  4. To confirm, click Delete.

    Deleting the reservation might take some time to complete.

gcloud

You can release reservations by using the delete command:

  gcloud compute reservations delete RESERVATION_NAME --zone ZONE

Replace the following:

  • RESERVATION_NAME: the name of the reservation that you want to delete.
  • ZONE: the zone where the reservation is located.

API

In the API, construct a DELETE request to the reservation.delete method.

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME

Replace the following:

  • PROJECT_ID: the project ID of the project that you used to create the reservation.
  • RESERVATION_NAME: the name of the reservation that you want to delete.
  • ZONE: the zone where the reservation is located.

After the delete command completes successfully, you are no longer charged for the reservation, and the resources are no longer reserved for you. Deleting a reservation has no effect on any running instances that were tied to that reservation. The running instances continue to run and you are still charged for those instances.

Attach reservations to commitments

Committed use discounts provide deeply discounted prices for your resources in exchange for 1-year or 3-year resource commitments, but they do not reserve capacity in specific zones. Reservations ensure that capacity is held in specific zones even if the reserved VMs are not running. By attaching reservations to a commitment, you can get discounted, reserved resources.

You must create and attach reservations to your commitment when you first purchase the commitment. You can attach multiple reservations to a single commitment but a reservation can only have one commitment.

After you purchase a commitment with an attached reservation, you cannot delete the reservation for the duration of the commitment. When your commitment expires or gets cancelled, Compute Engine automatically deletes any attached reservations.

However, you can replace a commitment's existing attached reservations with new ones. For more information on what can and cannot be changed in reservations that are created for a commitment, see Replace reservations that are attached to commitments.

Committed resources that do not require attached reservations

To purchase a commitment for vCPUs and/or memory, you do not need to reserve those resources. Nevertheless, you can still reserve vCPUs and/or memory and attach the reservation to the commitment in case you want Compute Engine to hold the capacity for those committed resources. To learn how to purchase commitments solely for vCPUs and/or memory and not reserve them, see Purchasing commitments for machine types.

Committed resources that require attached reservations

To purchase a commitment for GPUs and/or local SSDs, you must also reserve those resources. You can reserve your committed GPUs and/or local SSDs using a single or a combination of reservations. Your commitment for GPUs and/or local SSDs can also have vCPUs and/or memory as part of it, but you don't need to reserve the vCPUs or memory. To learn how to purchase commitments that have GPUs and/or local SSDs, see Purchase commitments with attached reservations.

Reserve more or less resources than you commit to

When you attach reservations to your commitment, you can reserve more or less amounts of vCPUs and/or memory than you are committing to. For example, when you purchase a commitment for 30 GB memory, you can reserve 10 GB memory, or 50 GB memory, or no memory at all. However, if your commitment has any GPUs and/or local SSDs, you must reserve and attach the exact number of GPUs and/or local SSDs that you are committing to. For example, if you purchase a commitment for 30 GB memory and 4 GPUs, you can reserve any amount of memory that you want to, but the reservation (or combination of reservations) that you attach must have exactly 4 GPUs. Consequently, you can reserve and attach vCPUs and/or memory even when you don't commit to them, but you cannot do so for GPUs and/or local SSDs.

Purchase commitments with attached reservations

When you purchase a commitment with attached reservations, make sure that your commitment and reservations meet the following criteria:

  • The commitment and its attached reservations must be in the same region.
  • The reservation must be for the same machine series as the commitment.
  • If your commitment has GPUs, then the GPU type in the reservation and the commitment must match.
  • For GPUs and local SSDs, the number of reserved resources of each resource type must exactly match with the number of committed resources for that resource type. For example, if you want to purchase a commitment for 4 V100 GPUs, then your commitment's attached reservations must have a total of 4 V100 GPUs. However, the amount of vCPU and memory that you reserve can be more or less than what you commit to.
  • For GPUs, purchase commitments for the specific GPU types that you intend to use. For example, you can purchase commitments for either NVIDIA P100s or NVIDIA V100s, but you cannot use a commitment that was purchased for NVIDIA P100 GPUs to cover NVIDIA V100 GPUs.

You can purchase a commitment with an attached reservation using the Google Cloud console, the gcloud CLI, or the API.

Console

Before you purchase a commitment using the Google Cloud console, select the project that you want to use to purchase the commitment. If discount sharing is enabled for a billing account, you can purchase the commitment using any project from that billing account. After you select the project, perform the following steps:

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

    Go to Committed use discounts

  2. To purchase a new commitment, click Purchase commitment.

  3. Name your commitment, and choose the Region where you want it to apply.

  4. Choose the Commitment type for your GPUs and/or local SSDs:
    General-Purpose N2 for N2 machine types
    General-Purpose N2D for N2D machine types
    General-Purpose N1 for N1 machine types
    Compute-optimized C2 for C2 machine types
    Accelerator-optimized A2 for accelerator-optimized machine types

  5. Choose a commitment Duration of 1 or 3 years.

  6. Enter the quantity of Cores and Memory that you want to purchase. If you only want to commit to and reserve GPUs or local SSDs without committing to vCPUs and memory, specify 0 for the vCPUs and memory commitment quantities.

  7. Click Add GPUs and select the GPU type and Number of GPUs that you want to commit to.

  8. Click Add local SSD and specify the number of disks that you want to commit to.

  9. To create a reservation and attach it to the commitment, click Add an item in the Reservations section.

    1. In the Name field, enter a name for your reservation.
    2. Choose the Region and Zone where you want to reserve resources.
    3. 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.

    4. In the Use with VM instance field, select one of the following options:

      • To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, select Select specific reservation.
      • To allow matching VM instances to automatically use this reservation, select Use reservation automatically.

    5. In the Number of VM instances field, enter the number of VM instances that you want to reserve.

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

      • 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 Plaform 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.

    7. To finish specifying the properties for this reservation, click Done.

  10. Click the Purchase button to purchase the commitment.

  11. Read the terms of purchase and click Purchase when you are ready to purchase the commitment.

gcloud

Use the gcloud compute commmitments create command to purchase a commitment, and include flags to create an attached reservation.

For example, the following commitment includes 4 GPUs and a new reservation for those 4 GPUs to be used across 2 n1-standard-32 instances in us-central1-a.

gcloud compute commitments create commitment-01 \
    --region=us-central1 \
    --project=myproject \
    --resources=vcpu=96,memory=624GB \
    --resources-accelerator=type=nvidia-tesla-v100,count=4 \
    --plan 12-month \
    --reservation=reservation-01 \
    --reservation-zone=us-central1-a \
    --machine-type=n1-standard-32 \
    --accelerator=type=nvidia-tesla-v100,count=2 \
    --vm-count=2

If you want to commit to and reserve GPUs or local SSDs without committing to vCPUs and memory, specify 0 for the vCPU and memory commitment quantities.

gcloud compute commitments create commitment-01 \
    --region=us-west2 \
    --project=myproject \
    --resources=vcpu=0,memory=0 \
    --resources-accelerator=type=nvidia-tesla-p4,count=1 \
    --plan 12-month \
    --reservation=reservation-01 \
    --reservation-zone=us-west2-b \
    --machine-type=n1-standard-2 \
    --accelerator=type=nvidia-tesla-p4,count=1 \
    --vm-count=1

To create multiple reservations when purchasing a commitment, use a YAML file that contains the reservation properties. For example:

gcloud compute commitments create commitment-01 \
    --region=us-central1 \
    --project=myproject \
    --resources=vcpu=96,memory=624,local-ssd=750 \
    --resources-accelerator=type=nvidia-tesla-v100,count=1 \
    --plan 12-month \
    --reservations-from-file=YAML_FILE

For example, the following YAML file contains 2 reservations. The first reservation, res-01, contains 1 n1-standard-2 instance with 1 GPU, and it is a targeted reservation, which means that you must specifically target that reservation by name to use its reserved instances. The second reservation, res-02, contains 1 n1-standard-2 VM instance with 2 types of attached local SSDs.

- reservation: res-01
  reservation_zone: us-central1-a
  require_specific_reservation: true
  vm_count: 1
  machine_type: n1-standard-2
  accelerator:
  - count: 1
    type: nvidia-tesla-v100
- reservation: res-02
  reservation_zone: us-central1-a
  vm_count: 1
  machine_type: n1-standard-2
  local_ssd:
  - interface: scsi
    size: 375
  - interface: nvme
    size: 375

API

Use the regionCommitments.insert method and include the reservations field to define the reservation's properties. For example, the following commitment includes 4 GPUs and a reservation for those 4 GPUs to be used across 2 instances in us-central1-a.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments

{
  "name": "commitment-01",
  "plan": "TWELVE_MONTH",
  "resources":
  [
    {
      "amount": "96",
      "type": "VCPU"
    },
    {
      "amount": "638976",
      "type": "MEMORY"
    },
    {
      "acceleratorType": "nvidia-tesla-v100",
      "amount": "4",
      "type": "ACCELERATOR"
    }
  ],
  "reservations":
  [
    {
      "name": "reservation-01",
      "specificReservation":
      {
        "count": "2",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 2,
              "acceleratorType": "nvidia-tesla-v100"
            }
          ],
          "machineType": "n1-standard-8"
        }
      },
      "specificReservationRequired": false,
      "zone": "us-central1-a"
    }
  ]
}

If you only want to commit to and reserve GPUs or local SSDs without committing to vCPUs and memory, specify 0 for the vCPU and memory commitment quantities. For example:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/commitments

{
  "name": "commitment-01",
  "plan": "TWELVE_MONTH",
  "resources":
  [
    {
      "amount": "0",
      "type": "VCPU"
    },
    {
      "amount": "0",
      "type": "MEMORY"
    },
    {
      "acceleratorType": "nvidia-tesla-v100",
      "amount": "4",
      "type": "ACCELERATOR"
    }
  ],
  "reservations":
  [
    {
      "name": "reservation-01",
      "specificReservation":
      {
        "count": "2",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 2,
              "acceleratorType": "nvidia-tesla-v100"
            }
          ],
          "machineType": "n1-standard-8"
        }
      },
      "specificReservationRequired": false,
      "zone": "us-central1-a"
    }
  ]
}

The commitment with the attached reservations is successfully created only if there are enough resources of the specified machine type in the target zone, and sufficient quota, at the time of the request.

When you create a commitment with an attached reservation, you cannot delete the reservation for the duration of the commitment. When your commitment expires, Compute Engine automatically deletes any attached reservations. The deletion of reservations has no effect on any running instances that were tied to those reservations. The running instances continue to run and you are still charged for those instances.

If you need to modify the properties of your committed reservations, see Replace reservations that are attached to commitments.

Replace reservations that are attached to commitments

Replace your commitment's existing attached reservations with new ones if you want to modify the types and numbers of VMs that use your committed resources. When you replace a commitment's existing attached reservation with a new reservation, you can make the following changes:

  • You can reserve VMs from a different machine type. However, you must still reserve VMs from the same machine family in order to continue receiving committed use discounts for your reserved resources.
  • You can change the number of VMs that you want to reserve.
  • You can change the quantity of GPUs and local SSDs that is attached per VM.

You can replace only one attached reservation at a time with exactly one new attached reservation. You can specify your replaced reservations to be either local or shared reservations.

When you replace your commitment's attached reservation with a new one, make sure that your new reservation meets the following requirements:

  • The new reservation must be in the same project as the commitment.

  • The new reservation must be in the same zone as the original reservation.

  • The number and types of GPUs in the new reservation must match with the ones in the original reservation.

  • The amount and types of local SSDs in the new reservation must match with the ones in the original reservation.

  • You can only change up to 100 VMs per request. To make a change that involves more than 100 VMs, divide the change into multiple smaller requests or reach out to Google Cloud Support.

You can replace a commitment's reservations using the gcloud CLI, or the API.. After you create the new reservations, you can make any necessary corresponding changes to your VMs.

gcloud

Use the gcloud beta compute commitments update-reservations command to update reservations that are attached to commitments.

For example, suppose you create a commitment with the following reservation:

  • res-1 has 4 n1-standard-2 instances, each with 1 P100 GPU (a total of 8 vCPUs and 4 P100 GPUs). The total reserved resources include the 4 P100 GPUs.

You can create the example commitment with the following command:

gcloud beta compute commitments create my-commitment-with-reservations \
    --region=asia-east1 \
    --resources=vcpu=10,memory=32GB \
    --resources-accelerator=type=nvidia-tesla-p100,count=4 \
    --plan 12-month \
    --reservations-from-file=one-reservation.yaml

where the one-reservation.yaml file contains the following:

- reservation: res-1
  reservation_zone: asia-east1-a
  require_specific_reservation: true
  vm_count: 4
  machine_type: n1-standard-2
  accelerator:
  - count: 1
    type: nvidia-tesla-p100

You can update the example commitment to replace the existing attached reservation with a new one. For this example, suppose you want to replace the attached reservation res-1 with a new reservation res-2, you can achieve this by doing the following:

  • Delete res-1 that has 4 n1-standard-2 instances, each with 1 P100 GPU (a total of 8 vCPUs and 4 P100 GPUs).
  • Create and attach res-2 with 2 n1-standard-2 instances, each with 2 P100 GPU (a total of 4 vCPUs and 4 P100 GPUs).

Notably, the total number of reserved GPUs within the commitment remains constant at 4.

To make the example update, use the following command:

gcloud beta compute commitments update-reservations my-commitment-with-reservations \
    --region=us-central1 \
    --reservations-from-file=two-reservations.yaml

where the two-reservations.yaml file contains the following:

- reservation: res-1
  reservation_zone: asia-east1-a
  require_specific_reservation: true
  vm_count: 1
  machine_type: n1-standard-2
  accelerator:
  - count: 1
    type: nvidia-tesla-p100
- reservation: res-2
  reservation_zone: asia-east1-a
  require_specific_reservation: true
  vm_count: 3
  machine_type: n1-standard-2
  accelerator:
  - count: 1
    type: nvidia-tesla-p100

API

Use the regionCommitments.updateReservations method.

For example, suppose you create a commitment with the following reservation:

  • res-1 has 4 n1-standard-2 instances each with 1 nvidia-tesla-p100 GPU (8 vCPUs and 4 P100 GPUs). The total reserved resources include the 4 P100 GPUs.

You can create the example commitment with the following command:

POST https://compute.googleapis.com/compute/beta/projects/my-project/regions/asia-east1/commitments/my-commitment-with-reservation/updateReservations

{
  "name": "my-commitment-with-reservation",
  "plan": "TWELVE_MONTH",
  "reservations":
  [
    {
      "name": "res-1",
      "specificReservation":
      {
        "count": "4",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 1,
              "acceleratorType": "nvidia-tesla-p100"
            }
          ],
          "machineType": "n1-standard-2"
        }
      },
      "specificReservationRequired": true,
      "zone": "asia-east1-a"
    }
  ],
  "resources":
  [
    {
      "amount": "10",
      "type": "VCPU"
    },
    {
      "amount": "32768",
      "type": "MEMORY"
    },
    {
      "acceleratorType": "nvidia-tesla-p100",
      "amount": "4",
      "type": "ACCELERATOR"
    }
  ]
}

You can update the example commitment to replace the existing attached reservation with a new reservation.

For example, suppose you want to replace the attached reservation res-1 with a new single-project reservation res-2, you can achieve this by doing the following:

  • Delete res-1 that has 4 n1-standard-2 instances, each with 1 P100 GPU (a total of 8 vCPUs and 4 P100 GPUs).
  • Create and attach res-2 with 2 n1-standard-2 instances, each with 2 P100 GPU (a total of 4 vCPUs and 4 P100 GPUs).

Notably, the total number of reserved GPUs within the commitment remains constant at 4.

To make the example update, use the following API request:

POST https://compute.googleapis.com/compute/beta/projects/my-project/regions/asia-east1/commitments/my-commitment-with-reservation/updateReservations

{
  "reservations":
  [
    {
      "name": "res-2",
      "specificReservation":
      {
        "count": "2",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 1,
              "acceleratorType": "nvidia-tesla-p100"
            }
          ],
          "machineType": "n1-standard-2"
        }
      },
      "specificReservationRequired": true,
      "zone": "asia-east1-a"
    }
  ]
}

You can also update the example commitment to replace the existing attached reservation with a new shared reservation. Suppose you want to replace the attached single-project reservation res-1 with a reservation res-3 that is shared with project-1 and project-2, you can do so using the following API request:

POST https://compute.googleapis.com/compute/beta/projects/my-project/regions/asia-east1/commitments/my-commitment-with-reservation/updateReservations

{
  "reservations":
  [
    {
      "name": "res-3",
      "specificReservation":
      {
        "count": "6",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 1,
              "acceleratorType": "nvidia-tesla-p100"
            }
          ],
          "machineType": "n1-standard-2"
        }
      },
      "shareSettings": {
        "shareType": "SPECIFIC_PROJECTS",
        "projectMap": {
          "project-1": {
            "projectId": "project-1"
          },
          "project-2": {
            "projectId": "project-2"
          }
        }
      },
      "specificReservationRequired": true,
      "zone": "asia-east1-a"
    }
  ]
}

View reservation usage reports

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

The usage report shows:

  • Reserved resources that are in use. These entries appear as normal vCPU, memory, GPU, and local SSD resources.
  • 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 an instance 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 instance.
  • 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
...

What's next