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:
- Install or update to the latest version of the Google Cloud CLI.
- 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
Create a reservation for virtual machine (VM) instances using the Google Cloud console, Google Cloud CLI, or Compute Engine API.
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
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.
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 Google Cloud console, gcloud CLI, or Compute Engine API.
Console
In the Google Cloud console, go to the Committed use discounts page.
Click Create reservation to create a reservation for a single project that has no parent commitment.
Name your reservation.
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.
Choose the Region and Zone where you want to reserve resources.
Specify the Number of VM instances that you want to reserve.
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.
- For predefined machine types, select what you need from the list.
- For custom machine types, including a minimum CPU platform, or to add GPUs, click Customize and make your selections.
- Optionally, specify the number of Local SSD disks that you want to add to each instance and specify the Interface type to use.
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 examplen2-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, specifyn2
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, usen2-custom-4-5120
.
- For predefined machine types, use the format
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
andINTERFACE_2
: the type of interface you want the local SSDs for each instance to use. Valid options are:scsi
andnvme
. 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 examplen2-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, specifyn2
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, usen2-custom-4-5120
.
- For predefined machine types, use the format
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
andINTERFACE_2
: the type of interface you want the local SSDs for each instance to use. Valid options are:scsi
andnvme
. Each local SSD is 375 GB. Repeat thelocalSsds.diskSizeGb
andlocalSsds.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.
Troubleshooting
Learn how to troubleshoot reservation creation.
What's next
- Learn how to consume and manage reservations.