Creating a reservation for a single project

This document describes how to create a reservation of Compute Engine zonal resources that can only be used by the project that created it. Reservations provide a very high level of assurance in obtaining capacity for Compute Engine zonal resources.

If you want to create a reservation that can be used by more than one project, see Creating a shared reservation instead.

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 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.
• Review the limitations for reservations.

Creating a reservation for a single project

Create a reservation for virtual machine (VM) instances using the Google Cloud Console, gcloud command-line tool, or Compute Engine API.

A VM instance can only consume a reservation if the instance's properties exactly match the reservation's instance properties:

• Zone
• Machine type (machine family, vCPUs, and memory)
• Minimum CPU platform
• GPU type
• GPU count
• Local SSD interface
• Local SSD size

By default, a single-project reservation is automatically consumed by any matching VM instances that are created in the project. To create a reservation that isn't consumed automatically, use the specificReservationRequired option when creating the reservation or create an instance without consuming a reservation.

Note: After a reservation is successfully created, you are charged for the reserved resources until the reservation is deleted, even if the reservation is not being consumed. If you delete a reservation but don't delete the instances that are using the reserved resources, the resources still incur charges. For more information, see Reservation billing.

You don't 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, see Combining reservations with committed-use discounts.

To create a reservation for a single project, use the Cloud Console, gcloud tool, or Compute Engine API.

Permissions required for this task

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

• compute.reservations.create on the project

Console

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

   Go to Committed use discounts

2. Click Create reservation to create a reservation for a single project 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.

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 list.
     2. For custom machine types, including a 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 Create 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=375,interface=INTERFACE_1 \
    --local-ssd=size=375,interface=INTERFACE_2 \
    --zone=ZONE
    --project=PROJECT_ID

Replace the following:

• RESERVATION_NAME: the name of the reservation to create.

• MACHINE_TYPE: a predefined or custom machine type.

  • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.
  • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

  Replace the following:

  • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
  • CPUS: the number of vCPUs.
  • MEMORY: the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.

• MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

• NUMBER_OF_VMS: the quantity of VM instances to reserve.

• NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

• ACCELERATOR_TYPE: the type of accelerator.

• INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the --local-ssd flag for each local SSD that you want to add, up to 24 local SSDs per instance.

• ZONE: the zone in which to reserve resources.

• PROJECT_ID: Optional: the project id of the project that you want to reserve resources for. If the --project flag is omitted, the current project is used.

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

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

API

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

POST https://compute.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":"375",
          "interface":"INTERFACE_1"
        },
        {
          "diskSizeGb":"375",
          "interface":"INTERFACE_2"
        }
      ]
    }
  }
}

Replace the following:

• PROJECT_ID: the project id of the project that you want to reserve resources for.
• ZONE: the zone in which to reserve resources.
• RESERVATION_NAME: the name of the reservation to create.
• NUMBER_OF_VMS: the quantity of VM instances to reserve.

• MACHINE_TYPE: a predefined or custom machine type.

  • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.
  • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

  Replace the following:

  • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
  • CPUS: the number of vCPUs.
  • MEMORY: the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.

• MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

• NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

• ACCELERATOR_TYPE: the type of accelerator.

• INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the localSsds.diskSizeGb and localSsds.interface fields for each local SSD that you want to add, up to 24 local SSDs per instance.

Optionally add the "specificReservationRequired": true field, as shown in the following example, to indicate that only VM instances that explicitly target this reservation can use it.

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 a 375 GB local SSD:

POST https://compute.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
}

To see your created reservation—for example, to check if it has been automatically consumed any instances—describe the reservation.

If this reservation does not consume instances as expected, see Ensuring utilization of reservations.

What's next

• Learn how to consume and manage reservations.