Create 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 a single project. 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 Create 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 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.

Creating a reservation for a single project

A virtual machine (VM) instance 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

By default, a single-project reservation is automatically consumed by any matching VMs that are created in the same project as the reservation. 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 your reserved resources, you must create and attach the reservation to a commitment at the time of purchasing the commitment. Consequently, your reservation can either be a standalone reservation or a reservation that is attached to a commitment. For more information about purchasing a commitment with an attached reservation, see Combining reservations with committed-use discounts.

To create a reservation for a single project, use the Google Cloud console, gcloud CLI, Compute Engine API, or Terraform.

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.

3. In the Name field, enter a name for your reservation.

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

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

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

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

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

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

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

9. To create the reservation, click Create.

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 a reserved 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 a 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-a

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 a reserved 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
}

Terraform

To create a reservation, use the google_compute_reservation Terraform resource. To specify a reservation for a single project, omit the share_settings block (default) or set the share_type field to LOCAL.

compute_reservation/main.tf

View on GitHub

resource "google_compute_reservation" "gce_reservation_local" {
  name = "gce-reservation-local"
  zone = "us-central1-c"

  share_settings {
    share_type = "LOCAL"
  }

  specific_reservation {
    count = 1
    instance_properties {
      machine_type     = "n2-standard-2"
    }
  }
}

For more information about how to use Terraform, see Using Terraform with Google Cloud.

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

Troubleshooting

Learn how to troubleshoot reservation creation.

What's next

• Learn how to consume and manage reservations.