Reserving Compute Engine zonal resources

Create reservations for VM instances in a specific zone, using custom or predefined machine types, with or without additional GPUs or local SSDs, to ensure resources are available for your workloads when you need them. After you create a reservation, you begin paying for the reserved resources immediately and they remain available for your project to use indefinitely until the reservation is deleted.

Use reservations to ensure that your project has resources for future increases in demand, including planned or unplanned spikes, migrating large number of VMs, backup and disaster recovery, or for planned growth and buffer.

When you no longer need a reservation, delete the reservation to stop incurring charges for it. Because reservations consume resources just like normal VMs, each reservation is charged based on existing On-Demand rates, which include Sustained Use Discounts, and are eligible for Committed Use Discounts.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.

Benefits

Reservations provide the following benefits:

• Reserve machines so that they are always available even if you do not use them immediately.

• Create a reservation at any time and delete it any time to stop paying for it.

  Note: If the reservation is attached to a commitment, then the reservation cannot be deleted until the commitment contract has expired.

• Reservations are billed in the same way and at the same rate as the resources that they are reserving. As such, reserved resources qualify for committed and sustained use discounts.

Limitations and restrictions

Reservations have the following limitations and restrictions:

• Reservations apply only to Compute Engine, Cloud Dataproc, and Google Kubernetes Engine VM usage.
• Reservations do not apply to f1-micro or g1-small machine types, preemptible VMs, sole tenant nodes, or other services not listed above like Cloud SQL and Dataflow.
• You can reserve up to 1000 VM instances per reservation.
• You must have sufficient quota in your project for the resources you are reserving. If the reservation is successful, quota for that resource will be charged accordingly.
• Resources are allocated when the reservation is created. If there aren't enough resources in the zone at the time of the request, the reservation will fail with an insufficient capacity error.
• When combined with a committed use discount:
  • For committed use discounted pricing for GPUs and local SSDs, a reservation must be created when purchasing the commitment.
  • If the reservation is attached to a commitment, the reservation cannot be deleted.
  • You can only buy a 1-year commitment on K80 GPUs.
• Reservations that are not attached to a committed use discount can be held for any duration, but the same minimum charge of 1 minute applies as for regular instances.

How reservations work

Create reservations to reserve the VM instances you need. Once created, reservations ensure that those resources are always available for you to use. During the creation process, you can choose how a reservation is used. For example, you can choose for a reservation be automatically applied to any new or existing instances that match the reservation's properties (the default behavior), or specify that only a specific VM instance can consume a reservation.

In all cases, a VM instance can only use a reservation if its properties exactly match the properties of the reservation. Specifically, for an instance to consume a reservation, the instance must match the reservation's properties for:

• zone
• vCPU
• minimum CPU platform
• memory
• GPU
• local SSD

If a VM instance does match a reservation's properties, the default behavior is for all existing and new VM instances to consume the reservation automatically unless otherwise specified. For example, by default, if you create a reservation for 10 custom-8-10240 instances, and you already have 5 matching custom-8-10240 instances, then those 5 instances will consume 5 of the reservations. If you create an additional 3 matching instances, then another 3 reservations are consumed.

You can override this default behaviour by specifying certain options when creating reservations and instances.

• To create a reservation that should not be consumed automatically, use the specificReservationRequired option. These reservations can now only be used if you explicitly specify the reservation during instance creation.
• To specify that an instance should consume a reservation, use the reservationAffinity option when creating the instance or in the instance template. You can specify that an instance automatically consumes from any matching reservation, does not automatically consume from matching reservations, or only consumes from a specific reservation.

If you stop or delete an instance that is using a reservation, the instance no longer counts against the reservation and the reserved resources are available again.

If you delete a reservation but do not delete the instances that are using the reserved resources, the instances persist and you pay for them as usual.

Creating a reservation

Create a reservation for VM instances using the console, the gcloud command-line tool, or the API. By default, any VM instances that match a reservation's properties will automatically consume that reservation. To create a reservation that is not consumed automatically, use the specificReservationRequired option.

Note: After a reservation is successfully created, you will be charged for the resources until the reservation is deleted. If you delete a reservation but do not delete the instances that are using the reserved resources, the instance will continued to be billed. See the billing section for additional details.

You do not need to create a commitment in order to reserve resources. However, if you want committed use discount pricing on GPUs or local SSDs, you must create a reservation that includes those resources at the same time when purchasing your commitment. For more information, refer to Combining reservations with Committed Use Discounts.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.reservations.create on the project

Console

1. Go to the Committed Use Discounts page in the GCP Console.

   Go to the Committed Use Discounts page

2. Click Create reservation to create a standalone reservation that has no parent commitment.

   Note: To purchase a commitment with an attached reservation, which is required if you want committed use discount pricing on GPUs and local SSDs, see Combining reservations with committed use discounts.

3. Name your reservation.

4. If you only want to use this reservation's resources when creating matching instances that specifically target this reservation by name, under Use with VM instance, choose Select specific reservation.

5. Choose the Region and Zone where you want to reserve resources.

6. Specify the Number of VM instances that you want to reserve.

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

   • If you have an instance template, click Use instance template and select an instance template from the list.
   • Otherwise, click Specify machine type.
     1. For predefined machine types, select what you need from the drop- down menu.
     2. For custom machine types, including minimum CPU platform, or to add GPUs, click Customize and make your selections.
     3. Optionally, specify the number of Local SSD disks that you want to add to each instance and specify the Interface type to use.

8. Click the Create button to create the reservation.

gcloud

Use the gcloud compute reservations create command to create a new reservation.

gcloud compute reservations create [RESERVATION_NAME] \
    --machine-type=[MACHINE_TYPE] \
    --min-cpu-platform [MINIMUM_CPU_PLATFORM] \
    --vm-count=[NUMBER_OF_VMS] \
    --accelerator=count=[NUMBER_OF_ACCELERATORS],type=[ACCELERATOR_TYPE] \
    --local-ssd=size=[SIZE_IN_GB],interface=[INTERFACE] \
    --require-specific-reservation \
    --zone=[ZONE]

Where:

• [RESERVATION_NAME] is the name of the reservation to create.
• [MACHINE_TYPE] is the machine type. For example, n1-standard-1. For custom machine types, use the format custom-[CPUS]-[MEMORY] where:
  • [CPUS] is the number of vCPUs.
  • [MEMORY] is the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, 5 GB of memory is 5120 MB: custom-4-5120. For a full list of restrictions, read the Specifications for custom machine types.
• [MINIMUM_CPU_PLATFORM] is the minimum CPU to use for each instance.
• [NUMBER_OF_VMS] is the quantity of VM instances to reserve.
• [NUMBER_OF_ACCELERATORS] is the number of GPUs to add, per instance.
• [ACCELERATOR_TYPE] is the type of accelerator.
• [SIZE_IN_GB] is the amount in GB of the local SSD to attach to each instance. The amount must be a multiple of 375.
• [INTERFACE] is the type of interface the local SSD should use. Valid options are: scsi and nvme. for each instance.
• [ZONE] is the zone in which to reserve resources.

Optionally, add the --require-specific-reservation flag to indicate that only VM instances that explicitly targets this reservation can use it. See How reservations work for more information about configuration options for consuming reserved resources.

For example, to make a reservation in us-central1-a that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves 10 custom machines, each with 8 Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and 375 GB local SSD:

gcloud compute reservations create my-reservation \
    --machine-type=custom-8-10240 \
    --min-cpu-platform "Intel Haswell" \
    --vm-count=10 \
    --accelerator=count=2,type=nvidia-tesla-v100 \
    --local-ssd=size=375,interface=scsi \
    --require-specific-reservation \
    --zone us-central1-c

To see a list of all available flags, see the gcloud compute reservations create reference.

API

In the API, construct a POST request to the reservations.insert method. In the request body, include the following parameters:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/reservations

{
  "name":"[RESERVATION_NAME]",
  "specificReservation":{
    "count":"[NUMBER_OF_VMS]",
    "instanceProperties":{
      "machineType":"[MACHINE_TYPE]",
      "minCpuPlatform": "[MINIMUM_CPU_PLATFORM]",
      "guestAccelerators":[
        {
          "acceleratorCount":"[NUMBER_OF_ACCELERATORS]",
          "acceleratorType":"[ACCELERATOR_TYPE]"
        }
      ],
      "localSsds":[
        {
          "diskSizeGb":"[SIZE_IN_GB]",
          "interface":"[INTERFACE]"
        }
      ]
    }
  }
}

Where:

• [PROJECT_ID] is the project ID for the request.
• [ZONE] is the zone in which to reserve resources.
• [RESERVATION_NAME] is the name of the reservation that you are creating.
• [NUMBER_OF_VMS] is the quantity of VM instances to reserve.
• [MACHINE_TYPE] is a predefined or custom machine type. For example, n1-standard-1. For custom machine types, use the format custom-[CPUS]-[MEMORY] where:
  • [CPUS] is the number of vCPUs.
  • [MEMORY] is the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, 5 GB of memory is 5120 MB: custom-4-5120. For a full list of restrictions, read the Specifications for custom machine types..
• [MINIMUM_CPU_PLATFORM] is the minimum CPU for each instance.
• [NUMBER_OF_ACCELERATORS] is the number of GPUs to add, per instance.
• [ACCELERATOR_TYPE] is the type of accelerator.
• [SIZE_IN_GB] is the amount in GB of the local SSD to attach to each instance. The amount must be a multiple of 375.
• [INTERFACE] is the type of interface the local SSD should use. Valid options are: scsi and nvme.

Optionally, include the specificReservationRequired boolean field to specify that only VM instances that specifically target this reservation by name can use this reservation. See How reservations work for more information about configuration options for using the instances in your reservations.

For example, to reserve resources in us-central1-a that can only be consumed when this reservation is specifically targeted, construct a request similar to the following. This example reserves 10 custom machines, each with 8 Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and 375 GB local SSD:

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

{
  "name": "reservation-1",
  "specificReservation":
  {
    "count": "10",
    "instanceProperties":
    {
      "machineType": "custom-8-10240",
      "minCpuPlatform": "Intel Haswell",
      "guestAccelerators":
      [
        {
          "acceleratorCount": 2,
          "acceleratorType": "nvidia-tesla-v100"
        }
      ],
      "localSsds":
      [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    }
  },
  "specificReservationRequired": true
}

Consuming reserved instances

When you create an instance, you choose whether the instance uses any available matching reservation (default), uses a specific reservation, or uses no reservation at all, by setting the instance's reservation affinity flag. For an instance to consume from a specific reservation, that reservation must be created with the corresponding specific reservation required flag. See How reservations work for more information.

Consuming instances from any matching reservation

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

When creating your reservations, exclude the --require-specific-reservation flag so that matching instances can consume from these reservation automatically.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.reservations.create on the project

• compute.instances.create on the project
• compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings.
• compute.networks.use on the project if using a legacy network
• compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
• compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
• compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
• compute.address.use on the project if specifying a static address in the project
• compute.instances.setMetadata if setting metadata
• compute.instances.setTags on the instance if setting tags
• compute.instances.setLabels on the instance if setting labels
• compute.images.useReadOnly on the image if creating a new root persistent disk
• compute.disks.create on the project if creating a new root persistent disk with this instance
• compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
• compute.disks.use on the disk if attaching an existing disk in read-write mode
• compute.disks.setLabels on the disk if setting labels
• compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
• compute.snapshots.use on the snapshot if creating an instance from a snapshot

Console

1. Create an open reservation.

   1. Go to the Committed Use Discounts page in the GCP Console.

      Go to the Committed Use Discounts page

   2. Click Create reservation to create a standalone reservation that has no parent commitment.

      Note: To purchase a commitment with an attached reservation, which is required if you want committed use discount pricing on GPUs and local SSDs, see Combining reservations with committed use discounts.

   3. Name your reservation, for example: reservation-01.

   4. Under Use with VM instance, select Use reservation automatically so that any matching instances can automatically use this reservation.

   5. Choose the Region and Zone where you want to reserve resources.

   6. Specify the Number of VM instances that you want to reserve.

   7. Specify the resources that you want each instance to have: number of vCPUs, minimum CPU platform, amount of memory, GPUs, and local SSD, as required.

   8. Click the Create button to create the reservation.

2. Create a VM instance that targets any open reservation and that matches the reservation's instance properties.

   1. Go to the VM instances page.

      Go to the VM instances page

   2. Select your project and click Continue.
   3. Click the Create instance button.
   4. Specify a Name for your instance.
   5. Specify a Machine type that matches the properties of reservation-01. For example, if you specified a minimum CPU platform or GPUs in the reservation, then to consume the reservation, you must customize this instance to match the reservation.
   6. If your reservation includes local SSDs, under Disks click Add new disk to add local SSDs that match the reservation.
   7. Under Management, under Reservations, select Automatically use created reservation.
   8. Click Create.

gcloud

1. Create an open reservation called reservation-01.

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

2. Create a VM instance that targets any open reservation and that matches the instance properties of reservation-01, including the zone, vCPU, minimum CPU platform, memory, GPUs, and local SSD properties.

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

API

1. Create an open reservation named reservation-01.

   POST https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations
   
   {
     "name":"reservation-01",
     "specificReservation":{
       "count":"2",
       "instanceProperties":{
         "machineType":"n1-standard-32",
         "minCpuPlatform": "Intel Haswell",
       }
     },
     "specificReservationRequired": false
   }
   

2. Create a VM instance that targets any open reservation and that matches the instance properties of reservation-01, including the zone, vCPU, minimum CPU platform, memory, GPUs, and local SSD properties

   POST https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances
   
   {
     "name": "instance-1",
     "machineType": "zones/us-central1-a/machineTypes/n1-standard-32",
     "minCpuPlatform": "Intel Haswell",
     "reservationAffinity":
     {
       "consumeReservationType": "ANY_RESERVATION"
     },
     ...
   }
   

Consuming instances from a specific reservation

In this model, only new instances that target a specific reservation by name consume that reservation. 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 the reservation should not be used automatically. 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 targeted reservation named reservation-02 and then create a matching instance to use resources from that reservation.

Console

1. Create a reservation with resources that can only be used by instances that specifically target this reservation by name.

   1. Go to the Committed Use Discounts page in the GCP Console.

      Go to the Committed Use Discounts page

   2. Click Create reservation to create a standalone reservation that has no parent commitment.

      Note: To purchase a commitment with an attached reservation, which is required if you want committed use discount pricing on GPUs and local SSDs, see Combining reservations with committed use discounts.

   3. Name your reservation, for example: reservation-02.

   4. Under Use with VM instance, check Select specific reservation so that only matching instances that specifically target this reservation by name can use this reservation.

   5. Choose the Region and Zone where you want to reserve resources.

   6. Specify the Number of VM instances that you want to reserve.

   7. Specify the resources that you want each instance to have: number of vCPUs, minimum CPU platform, amount of memory, GPUs, and local SSD, as required.

   8. Click the Create button to create the reservation.

2. Create a VM instance that targets the reservation by name and that matches the reservation's instance properties.

   1. Go to the VM instances page.

      Go to the VM instances page

   2. Select your project and click Continue.
   3. Click the Create instance button.
   4. Specify a Name for your instance.
   5. Specify a Machine type that matches the properties of reservation-01. For example, if you specified a minimum CPU platform in the reservation, then to consume the reservation, you must customize this instance to match the reservation.
   6. If your reservation includes local SSDs, under Disks click Add new disk to add local SSDs that match the reservation.
   7. Under Management, under Reservations, select an available reservation with matching properties, for example: reservation-02.
   8. Click Create to create the instance.

gcloud

1. Create a reservation named reservation-02 with resources that can only be used by instances that specifically target this reservation by name.

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

2. Create a VM instance that targets reservation-02 by name and that matches that reservation's instance properties including: zone, vCPU, minimum CPU platform, memory, GPUs, and local SSD properties.

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

API

1. Create a reservation named reservation-02 with resources that can only be used by instances that specifically target this reservation by name.

   POST https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations
   
   {
     "name":"reservation-02",
     "specificReservation":{
       "count":"10",
       "instanceProperties":{
         "machineType":"n1-standard-32",
         "minCpuPlatform": "Intel Haswell",
       }
     },
     "specificReservationRequired": true
   }

2. Create a VM instance that targets reservation-02 by name and that matches that reservation's instance properties for: zone, vCPU, minimum CPU platform, memory, GPUs, and local SSD.

   POST https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances
   
   {
     "name": "instance-2",
     "machineType": "zones/us-central1-a/machineTypes/n1-standard-32",
     "minCpuPlatform": "Intel Haswell",
     "reservationAffinity":
     {
       "consumeReservationType": "SPECIFIC_RESERVATION",
       "key": "compute.googleapis.com/reservation-name",
       "values":
       ["reservation-02"
       ]
     },
     ...
   }

Creating instances without consuming reservations

To avoid consuming resources from any reservation, set the reservation affinity flag to "none" when creating the VM.

Console

1. Create an instance which does not consume from a reservation.
   1. Go to the VM instances page.

      Go to the VM instances page

   2. Click the Create instance button.
   3. Create an instance as usual.
   4. Under Management, under Reservations, select Don't use to ensure that this instance does not consume from any existing reservations.
   5. Click Create to create the instance.

gcloud

Create an instance which does not consume from a reservation.

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

API

Create an instance which does not consume from a reservation.

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

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

Listing and describing reservations

List and view details about your reservation using the console, the gcloud command-line tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.reservations.list on the project to list reservations
• compute.reservations.get on the project or on the reservation, to describe a reservation

Console

1. Go to the Committed Use Discounts page in the GCP Console.

   Go to the Committed Use Discounts page

2. Click Reservations to see a list of your reservations.

The list of reservations includes details about each reservation. You can use the Machines used (total) column to determine the utilization of each reservation.

gcloud

List your reservations with the gcloud compute reservations list command:

gcloud compute reservations list [--filter="zone:('[ZONE]')"]

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

Describe your reservations with the gcloud compute reservations describe command:

gcloud compute reservations describe [RESERVATION_NAME] --zone=[ZONE]

creationTimestamp: '2019-04-01T08:29:10.210-07:00'
id: '702162498650398927'
kind: compute#reservation
name: reservation-04
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04
selfLinkWithId: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/702162498650398927
specificReservation:
  count: '50'
  inUseCount: '25'
  instanceProperties:
    machineType: n1-standard-1
specificReservationRequired: true
status: READY
zone: https://www.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 have been reserved and 25 of them are currently used.

API

In the API, list your reservations by making a GET request to the reservations.list method.

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

Describe a reservation by calling the reservations.get method.

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

{
 "id": "702162498650398927",
 "creationTimestamp": "2019-04-01T08:29:10.210-07:00",
 "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
 "selfLinkWithId": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/702162498650398927",
 "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
 "name": "reservation-04",
 "specificReservationRequired": false,
 "status": "READY",
 "kind": "compute#reservation",
 "specificReservation": {
  "instanceProperties": {
   "machineType": "n1-standard-32"
  },
  "count": "50",
  "inUseCount": "25"
 }
}

You can use the count and inUseCount values to determine the utilization of each reservation. In this example 50 instances have been reserved and 25 of them are currently used.

Modifying reservations

You can resize or delete a reservation if it is not attached to a commitment.

Resizing a reservation

You can resize the number of VMs in a reservation that is not tied to a commitment by using the gcloud command-line tool or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.reservations.resize on the reservation

gcloud

Resize your reservation using gcloud compute reservations update cmd. For example:

Create a reservation for 2 VMs:

gcloud compute reservations create reservation-01 \
    --machine-type=n1-standard-32 \
    --zone=us-central1-a \
    --vm-count=2

Resize the reservation from 2 to 10 VMs:

gcloud compute reservations update reservation-01 \
    --zone=us-central1-a \
    --vm-count=10

API

In the API, construct a POST request to the reservations.resize method and include the new specificSkuCount in the request body. The following request body updates the reservation's VM count to 10.

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

{"specificSkuCount": "10"}

The update request will succeed if there are enough resources in the target zone, and sufficient quota in the target region, at the time of the request.

Deleting a reservation

You can delete reservations that are not tied to a commitment by using the console, the gcloud command-line tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.reservations.delete on the reservation

Console

1. Go to the Committed Use Discounts page in the GCP Console.

   Go to the Committed Use Discounts page

2. Click Reservations to see a list of your reservations.

3. Click the checkbox next to each reservation that you want to delete.

   Note: If the reservation has a parent commitment, it cannot be deleted.

4. Click Delete reservation.

gcloud

You can release reservations by using the delete command:

gcloud compute reservations delete [RESERVATION_NAME] --zone [ZONE]

API

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

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

Once the delete command completes successfully, you will no longer be charged for the reservation and the resources will no longer be reserved for you. Deleting a reservation has no effect on any running instances that were tied to that reservation; you are still charged for those instances.

Combining reservations with Committed Use Discounts

A Committed Use Discount provides a 1- or 3-year discounted price agreement, but it does not reserve capacity in a specific zone. A reservation ensures that capacity is held in a specific zone even if the reserved VMs are not running. By combining a reservation with a commitment, you can get discounted, reserved resources.

By default, when you create a reservation, any applicable committed use discounts for cores and memory will automatically apply to your VM instances. However, to get committed use discount rates for GPUs and local SSDs, you must create a reservation for those resources when purchasing the commitment.

Once you purchase a commitment, it is not possible to cancel it. See Committed use discounts for more information.

Purchasing a commitment for GPUs or local SSDs

Beta

This product or feature is in a pre-release state and might change or have limited support. For more information, see Product launch stages.

To purchase a commitment for GPUs or local SSDs:

• You must purchase a general-purpose N1 commitment. GPUs are only supported with N1 machine types.
• You must create a reservation that includes either GPUs or local SSDs at the same time when you are purchasing your commitment.
• You do not need to commit to vCPUs or memory.

You must purchase commitments for specific GPU types. For example, you might purchase either Tesla P100s or Tesla V100s, but you cannot purchase commitments for Tesla P100 GPUs and expect to apply them to other GPU types.

The amount of GPUs and local SSDs that you reserve must be equal to the amount that you commit to. For example, if you want to reserve 4 V100 GPUs, then you must also commit to 4 V100 GPUs. However, the amount of vCPU and memory that you reserve can be more or less than what you commit to.

If you only want to commit to GPUs or local SSDs, you can specify 0 for vCPU and memory commitments. But the reservation that you attach to your commitment must contain the same GPUs and local SSDs as the commitment, as well as the machine types (with vCPUs and memory) that you want to reserve.

Note: You do not need to specify a commitment type because the commitment automatically defaults to general purpose. You can only purchase GPUs and local SSDs for general-purpose commitments.

Purchase a commitment with an attached reservation using the console, the gcloud tool, or the API.

Console

1. Go to the Committed Use Discounts page in the GCP Console.

   Go to the Committed Use Discounts page

2. Click Purchase commitment to purchase a new commitment.
3. Name your commitment and choose the region where you want it to apply.
4. For Commitment type, select General Purpose.
5. Choose a duration amount of the commitment, either 1 or 3 years.

6. Choose the input mode for the commitment:

   • (Recommended) Custom input allows you to customize the number of vCPUs and the of memory.

   • Basic input allows you to choose the number of vCPUs and Compute Engine will automatically populate the amount of memory for the number of vCPUs.

7. Enter the quantities of vCPU and memory that you want to purchase. Memory per vCPU must be a specific ratio depending on the discount type that you select. Use between 0.9 GB and 6.5 GB per vCPU for standard committed use discounts. The total memory must be a multiple of 256 MB.

   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.

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

9. Click Add local SSD and specify the number of disk that you want to commit to.

10. Click Add new reservation to create one or more reservations for instances that will use the GPUs and local SSDs.

    1. Name your reservation.
    2. Under Use with VM instance:
       • If you want to use this reservation's resources only when creating matching instances that specifically target this reservation by name, select Select specific reservation.
       • If you want matching instances to automatically use this reservation, select Use reservation automatically.
    3. Choose the Region and Zone where you want to reserve resources.
    4. Specify the Number of VM instances that you want to reserve.
    5. Specify the resources that you want to reserve for each instance:
       • If you have an instance template, click Use instance template and select an instance template from the list.
       • Otherwise, click Specify machine type.
         1. For predefined machine types, select what you need from the drop-down menu.
         2. For custom machine types, including minimum CPU platform, or to add GPUs, click Customize and make your selections.
         3. Optionally, specify the number of Local SSD disks that you want to add to each instance and specify the Interface type to use.
    6. Click the Create button to create the reservation.
    Note: The amount of GPUs and local SSDs that you reserve must be equal to the amount that you commit to.

11. Click the Purchase button to purchase the commitment.

12. Read the terms of purchase and click Purchase again once you are ready to purchase the commitment.

gcloud

Use the gcloud beta 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 beta compute commitments create commitment-01 \
    --region=us-central1 \
    --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-16 \
    --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 beta compute commitments create commitment-01 \
    --region=us-west2 \
    --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-1 \
    --accelerator=type=nvidia-tesla-p4,count=1 \
    --vm-count=1

To create multiple reservations when purchasing a commitment, use a YAML file. For example:

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

Where [YAML_FILE] contains the reservation properties.

For example, the following YAML file contains 2 reservations. The first reservation, res-01, contains 1 n1-standard-1 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-1 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-1
  accelerator:
  - count: 1
    type: nvidia-tesla-v100
- reservation: res-02
  reservation_zone: us-central1-a
  vm_count: 1
  machine_type: n1-standard-1
  local_ssd:
  - interface: scsi
    size: 375
  - interface: nvme
    size: 375

API

Use the regionCommitments.insert API 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://www.googleapis.com/compute/beta/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 amounts. For example:

POST https://www.googleapis.com/compute/beta/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 will be successfully created only if there are enough resources 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.

If you need to transfer GPUs or local SSDs across committed reservations, see Modifying reservations that are attached to commitments.

Modifying reservations that are attached to commitments

If a commitment has one or more reservations with GPUs or local SSDs, you can use the gcloud tool or the API to transfer GPUs or local SSDs across those reservations. For example, you might move GPUs from one reservation to a second, new reservation.

Limitations:

• You can only move resources between two reservations, where one is the source reservation and the other is the destination. The source reservation must already exist; the destination can be an existing or new reservation.
• The source and destination reservations must be in the same zone.
• You cannot modify the resource properties in existing reservations; you can only transfer existing resources from one reservation to another.
• The total amount of GPUs and local SSDs must remain constant.
• You can only change 100 VMs per request. If you want to update more, call the API multiple times or reach out to Google Cloud Support.

• You cannot transfer vCPUs or memory or modify other properties of attached reservations.

gcloud

Use the gcloud beta compute commitments update-reservations command.

Create a commitment with one reservation: res-1 has 4 n1-standard-1 instances each with 1 P100 GPU (4 vCPUs and 4 P100 GPUs). The total reserved resources includes 4 P100 GPUs.

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 one-reservation.yaml contains:

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

Update the commitment to transfer some resources from res-1 to a new, second reservation, res-2. In this example:

• Modify res-1 to have 2 n1-standard-1 instance each with 2 P100 GPUs (2 vCPU and 2 P100 GPUs).
• Add res-2 to have 2 n1-standard-2 instances each with 1 P100 GPU. (4 vCPUs and 2 P100 GPUs).

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

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

Where two-reservations.yaml contains:

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

API

Use the regionCommitments.updateReservations method.

For example, create a commitment with the following reservation:

• res-1 has 4 n1-standard-1 instances each with 1 nvidia-tesla-p100 GPU (4 vCPUs and 4 P100 GPUs).

In this example, the total reserved resources includes 4 P100 GPUs.

POST https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/regions/us-central1/commitments

{
  "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-1"
        }
      },
      "specificReservationRequired": true,
      "zone": "asia-east1-a"
    }
  ],
  "resources":
  [
    {
      "amount": "10",
      "type": "VCPU"
    },
    {
      "amount": "32768",
      "type": "MEMORY"
    },
    {
      "acceleratorType": "nvidia-tesla-p100",
      "amount": "4",
      "type": "ACCELERATOR"
    }
  ]
}

Update the commitment to transfer some resources from res-1 to a new, second reservation, res-2. In this example:

• Modify res-1 to have 2 n1-standard-1 instance each with 2 P100 GPUs (2 vCPU and 2 P100 GPUs).
• Add res-2 to have 2 n1-standard-2 instances each with 1 P100 GPU. (4 vCPUs and 2 P100 GPUs).

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

POST https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/regions/us-central1/commitments/my-commitment-with-reservation/updateReservations

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

Viewing 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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/[RESOURCE_TYPE]/[RESOURCE_NAME]. For example, https://www.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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/reservations/[RESERVATION_NAME]. For example, https://www.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-a/reservations/my-reservation
Total reserved resources	com.google.cloud/services/compute-engine/Reservation[SKU_NAME]	https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/reservations/[RESERVATION_NAME]. For example, https://www.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-a/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/VmimageN1StandardRam,166970074857472,byte-seconds,https://www.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/VmimageN1StandardRam,166970074857472,byte-seconds,https://www.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/ReservationN1StandardRam,333940149714944,byte-seconds,https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/reservations/my-reservation,7.58809E+17,us-central2-a
...

Reservation billing

Reservations are billed at the same rate as the resources that they are reserving. Sustained use discounts, committed use discounts and custom pricing apply as they would to regular VMs.

Take the following example:

• You have a 3 vCPU commitment in us-central1
• You are running 5 vCPUs in us-central1-a
• You have a 10 vCPU reservation in us-central1-a

You will be billed as follows:

Covered by	# of vCPUs
Committed Use Discount price	3
On-demand price (2 vCPU used reservations + 5 vCPU unused reservations)	7

What's next

• Learn more about committed use discounts