Consume and manage reservations

This document describes how to consume and manage reservations for Compute Engine zonal resources. Reservations provide a very high level of assurance in obtaining capacity for Compute Engine zonal resources. Each reservation provides assurance for one or more virtual machine (VM) instances with the same properties. To learn about reservations, see Reservations of Compute Engine zonal resources. To learn how to create reservations, see Create a reservation for a single project or Create a shared reservation.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the Google Cloud CLI.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Review the requirements and restrictions for reservations.

Consuming 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 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 all the following properties for both the VM and reservation are exactly matching:

• Project
• Zone
• Machine type
• Minimum CPU platform
• GPU type and count
• Local SSD type and count

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.

Consuming 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.

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.addresses.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.useReadOnly on the snapshot if creating an instance from a snapshot

Console

1. Create a reservation with resources that can be used by instances with a reservation affinity property configured to consume any reservations (default).

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

      Go to Committed use discounts

   2. To create a standalone reservation that has no parent commitment, click Create reservation.

      Note: For information about how 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
      • 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 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.

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

      Go to Create an instance

   2. Specify a name for your VM.

   3. In the Machine type section, specify a machine 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 VM to match the reservation.

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

      1. Expand the Disks section.
      2. If your reservation includes local SSDs, to add local SSDs that match the reservation's local SSD interface and amount, click Add local SSDs.
      3. Expand the Management section.
      4. In the Reservations list, click Automatically use created reservation.

   5. 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" \
       --accelerator=count=2,type=nvidia-tesla-v100 \
       --local-ssd=size=375,interface=scsi \
       --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" \
       --accelerator=count=2,type=nvidia-tesla-v100 \
       --local-ssd=size=375,interface=scsi \
       --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"
     },
     ...
   }
   

Consuming 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 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 Consuming a specific single-project reservation or Consuming a specific shared reservation.

Consuming a specific single-project reservation

To consume a specific single-project reservation, use the Cloud console, gcloud CLI, or Compute Engine API.

Console

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

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

      Go to Committed use discounts

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

      Note: For information about how 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
      • Local SSD

   8. Click Create.

2. Create a VM instance that targets that specific reservation by name.

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

   2. Specify a name for your VM.

   3. In the Machine type section, select a machine 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.

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

      1. Expand the Disks section.
      2. If your reservation includes local SSDs, to add local SSDs that match the reservation's local SSD interface and amount, click Add local SSDs.
      3. Expand the Management section.
      4. In the Reservations list, select an available reservation with matching properties—for example, 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"
       ]
     },
     ...
   }

Consuming a specific shared reservation

To consume a specific single-project reservation, use the gcloud CLI or Compute Engine API.

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"
       ]
     },
     ...
   }

Creating 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 listing and describing 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 listing and describing reservations.

Troubleshooting

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

Listing and describing reservations

List and view details about your reservation using the console, the gcloud CLI, or the API.

Note: You can only list the reservations created by each project. Consequently, shared reservations are only listed under the owner project—you cannot list the reservations shared with each project or list all shared reservations in each organization. For recommendations about how to manage shared reservations, see best practices for shared reservations.

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. In the Cloud console, go to the Committed use discounts page.

   Go to Committed use discounts

2. Click Reservations.

The list of reservations includes details about each reservation. The Machines used (total) column describes the utilization of each reservation. For example, a reservation that displays 25 (50) is a reservation for 50 instances, and 25 of these instances have been consumed and are currently in use.

gcloud

View a list of 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

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

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

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

{
  "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",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2"
    },
    "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 a reservation by calling the reservations.get method.

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

{
  "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

Modifying reservations

Resize a reservation if you want to change the number of VMs reserved. Modify which projects can consume a shared reservation if you want to want to limit or expand consumption.

To change any other properties of a reservation, first create a new reservation then delete the older reservation.

Note: You can only 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 using the gcloud CLI 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 by using the gcloud compute reservations update command. For example:

For example, suppose you create a reservation for two VM instances:

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

To resize the example reservation from two to ten VM instances, use the following command:

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://compute.googleapis.com/compute/v1/projects/<var>PROJECT_ID</var>/zones/<var>ZONE</var>/reservations/<var>RESERVATION_NAME</var>/resize

{"specificSkuCount": "10"}

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

Modifying the consumer projects for a shared reservation

To modify the consumer projects for a shared reservation, use the gcloud CLI or the Compute Engine API. You can see the projects that a reservation is shared with by describing the reservation.

Permissions required for this task

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

• compute.reservations.resize on the reservation in the owner project

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 was created.
  • 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 was created.
  • 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 was created.
  • 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 was created.
• 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 Listing and describing reservations.

Deleting a reservation

Caution: If you delete a specific reservation that was consumed by one or more VMs, those VMs cannot consume any other reservation.

• To prevent this issue, delete the VMs that are consuming a specific reservation before deleting the specific reservation.
• To fix this issue:
  1. Recreate a new specific reservation with the same name and properties as the deleted specific reservation.
  2. Stop and start the affected VMs.

You can delete reservations that aren't tied to a commitment by using the console, the gcloud CLI, 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. In the Cloud console, go to the Committed use discounts page.

   Go to Committed use discounts

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

3. Select 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 <var>RESERVATION_NAME</var> --zone <var>ZONE</var>

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/<var>PROJECT_ID</var>/zones/<var>ZONE</var>/reservations/<var>RESERVATION_NAME</var>

Replace the following:

• PROJECT_ID: the project ID of the project that you used to create this 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; 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 are automatically applied 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.

After you purchase a commitment, you cannot cancel it. For more information, see Committed use discounts.

Purchasing a commitment for GPUs or local SSDs

Note: The following steps explain how to purchase commitments for GPUs that use the general-purpose N1 machine type. To purchase commitments for NVIDIA A100 GPUs, which are tightly coupled with the A2 machine types, follow the instructions for Purchasing commitments for machine types.

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 (with the exception of the A100 GPUs).
• 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 NVIDIA P100s or NVIDIA V100s, but you cannot purchase commitments for NVIDIA 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 Cloud console, the gcloud CLI, or the API.

Permissions required for this task

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

• compute.commitments.create to create a commitment for a VM.
• compute.commitments.list to view a list of commitments on a project.
• compute.commitments.updateReservations to create a reservation for GPUs or SSDs.

Console

Before you purchase a commitment using the 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. For Commitment type, select General Purpose.

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 vCPU 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. 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 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. Click Customize to use the slider to select the Cores and Memory for your machine type.
        2. Specify the CPU platform.
        3. To add GPUs, enter the number of GPUs and the GPU type.
        4. Optionally, specify the number of Local SSDs that you want to add to each instance and specify the Interface type to use.
   6. Click the Done 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.

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 \
    --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 \
    --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 \
    --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 is 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 CLI 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 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 transfer committed resources between different reservations. For this example, suppose you want to transfer some committed resources from res-1 to a new, second reservation, res-2; you can achieve this by doing the following:

• Modify res-1 to have 1 n1-standard-2 instance with 1 P100 GPU (2 vCPUs).
• Add res-2 to have 3 n1-standard-2 instances, each with 1 P100 GPU (a total of 6 vCPUs and 3 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 (4 vCPUs and 4 P100 GPUs).

In this example, the total reserved resources includes 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 transfer committed resources between different reservations. For this example, suppose you want to transfer some committed resources from res-1 to a new, second reservation, res-2; you can achieve this by doing the following:

• Modify res-1 to have 2 n1-standard-2 instances, 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).

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

To make the example update, use the following command:

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

{
  "reservations":
  [
    {
      "name": "res-1",
      "specificReservation":
      {
        "count": "2",
        "instanceProperties":
        {
          "guestAccelerators":
          [
            {
              "acceleratorCount": 1,
              "acceleratorType": "nvidia-tesla-p100"
            }
          ],
          "machineType": "n1-standard-2"
        }
      },
      "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://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-a/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-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/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

• Learn more about committed use discounts.