This document explains how to create a single-project reservation, which can be consumed only by virtual machine (VM) instances in the same project. To learn more about reservations, see Reservations of Compute Engine zonal resources.
For other methods of creating reservations, see instead the following pages:
If you have any 1-year or 3-years commitments in the current project, then your reserved resources automatically receive any applicable committed use discounts. You can also create and attach a reservation to a commitment when you purchase the commitment. To learn more, see Attach reservations to commitments.
To create a reservation that can be used by multiple projects, see Create a shared reservation.
Before you begin
- Review the requirements and restrictions for reservations.
-
If you haven't already, then set up authentication.
Authentication is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
Terraform
To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Required roles
To get the permissions that you need to create single-project reservations,
ask your administrator to grant you the
Compute Admin (roles/compute.admin
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to create single-project reservations. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create single-project reservations:
-
compute.reservations.create
on the project -
To specify an instance template:
compute.instanceTemplates.useReadOnly
on the instance template
You might also be able to get these permissions with custom roles or other predefined roles.
Create a single-project reservation
To consume a reservation, a VM must have properties that exactly match that reservation. To specify the properties of the VMs that you want to reserve, select one of the following sections in this document:
Recommended: Specify an instance template
This section explains how to use an instance template to define the properties of a reservation. By using an instance template, you can define the properties of a reservation and the VMs that can consume the reservation in the same place.
-
This section explains how to use an existing VM to define the properties of a reservation. By using the properties of an existing VM, you can consume the reservation by creating VMs with properties that match the reference VM.
-
This section explains how to directly define the properties of a reservation. This method requires you to manually ensure that the properties of your VMs and reservations exactly match—any mismatched properties prevent consumption.
By default, a reservation can be automatically consumed by any VMs with properties that match it. If you want to control reservation consumption, do one or more of the following:
Create a reservation that can only be consumed by VMs that specifically target it, as explained in the following sections in this document. Then, configure VMs to consume that specific reservation.
Configure VMs that can't consume any reservations.
Additionally, you can specify a compact placement policy when creating a single-project reservation. A compact placement policy specifies that VMs are to be located as close to each other as possible to reduce network latency.
Specify an instance template
To avoid errors when creating a reservation by specifying an instance template, make sure of the following:
Create your reservation in the same region and zone as the resources within the instance template. Any regional or zonal resources specified in an instance template—such as a machine type or a Persistent Disk volume—restrict the use of the template to the locations where those resources exist. For example, if your instance template specifies an existing Persistent Disk volume in zone
us-central1-a
, then you can only create your reservation in the same zone. To check if an existing template specifies any resources that bind the template to a specific region or zone, view the details of the instance template and look for references to regional or zonal resources inside of it.If the instance template specifies a compact placement policy, then make sure that the template specifies a supported machine type for compact placement policies. Otherwise, creating the reservation fails.
To create a single-project reservation by specifying an instance template, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), click
Create reservation.The Create a reservation page opens.
For Name, enter a name for your reservation.
For Region and Zone, select where you want to reserve resources.
In the Share type section, select Local if it isn't already selected.
Optional: To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, in the Google Cloud services section, select Share reservation.
In the Use with VM instance section, select one of the following options:
To allow matching VMs to automatically consume this reservation, select Use reservation automatically if it isn't already selected.
To consume this reservation's resources only when creating matching VMs that specifically target this reservation by name, select Select specific reservation.
For Number of VM instances, enter the number of VMs that you want to reserve.
In the Machine configuration section, do the following:
To specify the properties of your VMs from an existing instance template, select Use instance template.
In the Instance template field, select the instance template of your choice. If you select a regional instance template, then you can only reserve resources within the region of the instance template.
In the Auto-delete section, you can enable the auto-delete option to let Compute Engine automatically delete the reservation at a specific date and time. Automatically deleting reservations can be useful to avoid unnecessary charges when you stop consuming the reservation.
To create the reservation, click Create.
The Reservations page opens. Creating the single-project reservation might take up to a minute to complete.
gcloud
To create a single-project reservation, use the
gcloud compute reservations create
command.
To create a single-project reservation by specifying an instance template and without including any optional flags, run the following command:
gcloud compute reservations create RESERVATION_NAME \
--source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \
--vm-count=NUMBER_OF_VMS \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation to create.PROJECT_ID
: the ID of the project where you want to reserve resources and where the instance template exists.LOCATION
: the location of the instance template. Specify one of the following values:For a global instance template:
global
.For a regional instance template:
regions/REGION
. ReplaceREGION
with the region where the instance template is located. If you specify a regional instance template, then you can only reserve VMs within the same region as the template's region.
INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. If the instance template specifies an A3 machine type or a compact placement policy, then you must include the--require-specific-reservation
flag. This indicates that only VMs that specifically target the reservation can consume it. For more information, see Consume VMs from a specific reservation.NUMBER_OF_VMS
: the number of VMs to reserve.ZONE
: the zone in which to reserve resources.
For example, to create a reservation for ten VMs in zone us-central1-a
by
specifying a global instance template, run the following command:
gcloud compute reservations create my-reservation \
--source-instance-template=projects/example-project/global/example-instance-template \
--vm-count=10 \
--zone=us-central1-a
Optionally, you can do one or more of the following:
To specify that only VMs that specifically target this reservation can consume it, include the
--require-specific-reservation
flag.gcloud compute reservations create RESERVATION_NAME \ --source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \ --require-specific-reservation \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, use the
gcloud beta compute reservations create
command with the--reservation-sharing-policy=ALLOW_ALL
flag.gcloud beta compute reservations create RESERVATION_NAME \ --source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \ --reservation-sharing-policy=ALLOW_ALL \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
To enable Compute Engine to automatically delete the reservation, select one of the following methods:
To delete the reservation at a specific date and time, use the
gcloud beta compute reservations create
command with the--delete-at-time
flag.gcloud beta compute reservations create RESERVATION_NAME \ --delete-at-time=DELETE_AT_TIME \ --source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
DELETE_AT_TIME
with a date and time formatted as an RFC 3339 timestamp, which must be as follows:none YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-
).HH:MM:SS
: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:
).OFFSET
: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the reservation after a specific duration, use the
gcloud beta compute reservations create
command with the--delete-after-duration
flag.gcloud beta compute reservations create RESERVATION_NAME \ --delete-after-duration=DELETE_AFTER_DURATION \ --source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
DELETE_AFTER_DURATION
with a duration in days, hours, minutes, or seconds. For example, specify30m
for 30 minutes, or1d2h3m4s
for 1 day, 2 hours, 3 minutes, and 4 seconds.
Go
Java
Node.js
Python
REST
To create a single-project reservation, make a POST
request to the
reservations.insert
method.
To create a single-project reservation by specifying an instance template
and without including any optional flags, make the following POST
request:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations
{
"name": "RESERVATION_NAME",
"specificReservation": {
"count": "NUMBER_OF_VMS",
"sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to reserve resources and where the instance template exists.ZONE
: the zone in which to reserve resources.RESERVATION_NAME
: the name of the reservation to create.NUMBER_OF_VMS
: the number of VMs to reserve.LOCATION
: the location of the instance template. Specify one of the following values:For a global instance template:
global
.For a regional instance template:
regions/REGION
. ReplaceREGION
with the region where the instance template is located. If you specify a regional instance template, then you can only reserve VMs within the same region as the template's region.
INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. If the instance template specifies an A3 machine type or a compact placement policy, then you must include thespecificReservationRequired
field in the request body, and set the field totrue
. This indicates that only VMs that specifically target this reservation can consume it. For more information, see Consume VMs from a specific reservation.
For example, to create a reservation for ten VMs in zone us-central1-a
by
specifying a global instance template, make the following POST
request:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "my-reservation",
"specificReservation": {
"count": "10",
"sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-instance-template"
}
}
Optionally, you can do one or more of the following:
To specify that only VMs that specifically target this reservation can consume it, include the
specificReservationRequired
field in the request body, and set the field totrue
.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME" }, "specificReservationRequired": true }
To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, make a
POST
request to thebeta.reservations.insert
method. In the request body, include theserviceShareType
field and set it toALLOW_ALL
.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "reservationSharingPolicy": { "serviceShareType": "ALLOW_ALL" }, "specificReservation": { "count": "NUMBER_OF_VMS", "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME" } }
To enable Compute Engine to automatically delete the reservation, select one of the following methods:
To delete the reservation at a specific date and time, make a
POST
request to thebeta.reservations.insert
method. In the request body, include thedeleteAtTime
field.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "deleteAtTime": "DELETE_AT_TIME", "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME" } }
Replace
DELETE_AT_TIME
with a date and time formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-
).HH:MM:SS
: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:
).OFFSET
: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the reservation after a specific duration, make a
POST
request to thebeta.reservations.insert
method. In the request body, include thedeleteAfterDuration
field.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "deleteAfterDuration": { "seconds": "DELETE_AFTER_DURATION" }, "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME" } }
Replace
DELETE_AFTER_DURATION
with a duration in seconds. For example, specify86400
for 86,400 seconds (1 day).
Specify an existing VM
You can only create a reservation based on an existing VM in the same zone as the VM.
After creating the reservation, you can consume it by creating VMs with properties that match the reference VM. You can do this by doing one of the following:
Create and use an instance template as follows:
Create an instance template based on the reference VM without overriding the reference VM's properties.
Create VMs using the newly-created template by doing one or both of the following:
Create a VM based on the reference VM while ensuring that the properties of the new VM and the reference VM exactly match.
To create a single-project reservation that uses the properties of an existing VM, do the following:
In the Google Cloud console, go to the Reservations page.
Click
Create reservation.The Create a reservation page opens.
For Name, enter a name for your reservation.
For Region and Zone, select where you want to reserve resources.
In the Share type section, click Local if it isn't already selected.
In the Use with VM instance section, select one of the following options:
To allow matching VMs to automatically consume this reservation, select Use reservation automatically if it isn't already selected.
To consume this reservation's resources only when creating matching VMs that specifically target this reservation by name, select Select specific reservation.
For Number of VM instances, enter the number of VMs that you want to reserve.
In the Machine configuration section, do the following:
Select Use existing VM.
For Existing VM, select the VM which properties you want to use to create the reservation.
Optional: To specify a compact placement policy for a reservation that meets the requirements, in the Group placement policy section, click the Select or create a group placement policy list, and then do one of the following:
To create a compact placement policy to specify in this reservation, do the following:
Click Create group placement policy.
The Create a group placement policy pane appears.
For Policy name, enter a name for your policy.
Click Create.
Creating the compact placement policy might take a few seconds to complete.
Otherwise, select an existing compact placement policy.
In the Auto-delete section, you can enable the auto-delete option to let Compute Engine automatically delete the reservation at a specific date and time. Automatically deleting reservations can be useful to avoid unnecessary charges when you stop consuming the reservation.
To create the reservation, click Create.
The Reservations page opens. Creating the reservation might take up to a minute to complete.
Specify properties directly
To create a single-project reservation by specifying properties directly, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), click
Create reservation.The Create a reservation page opens.
For Name, enter a name for your reservation.
For Region and Zone, select where you want to reserve resources.
In the Share type section, click Local if it isn't already selected.
Optional: To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, in the Google Cloud services section, select Share reservation.
In the Use with VM instance section, select one of the following options:
To allow matching VMs to automatically consume this reservation, select Use reservation automatically if it isn't already selected.
To consume this reservation's resources only when creating matching VMs that specifically target this reservation by name, select Select specific reservation.
For Number of VM instances, enter the number of VMs that you want to reserve.
In the Machine configuration section, select Specify machine type, and then specify the following:
For Machine family, Series, and Machine type, select a machine family, series, and machine type.
Optional: To specify a minimum CPU platform or attach GPUs to N1 VMs, do the following:
To expand the CPU Platform and GPU section, click the
expander arrow.Optional: To specify a minimum CPU platform, for CPU Platform, select an option.
Optional: To attach GPUs to N1 VMs, click
Add GPU. Then, for GPU type and Number of GPUs, select the type and number of GPUs to attach to each N1 VM.
Optional: To add Local SSD disks, do the following:
For Number of disks, select the number of Local SSD disks for each VM.
For Interface type, select the interface for the Local SSD disks.
Optional: To specify a compact placement policy for a reservation that meets the requirements, click the Select or create a group placement policy list, and then do one of the following:
To create a compact placement policy to specify in this reservation, follow these steps:
Click Create group placement policy.
The Create a group placement policy pane appears.
For Policy name, enter a name for your policy.
Click Create.
Creating the compact placement policy might take a few seconds to complete.
Otherwise, select an existing compact placement policy.
Optional: To specify a compact placement policy for a reservation that meets the requirements, in the Group placement policy section, click the Select or create a group placement policy list, and then do one of the following:
To create a compact placement policy to specify in this reservation, do the following:
Click Create group placement policy.
The Create a group placement policy pane appears.
For Policy name, enter a name for your policy.
Click Create.
Creating the compact placement policy might take a few seconds to complete.
Otherwise, select an existing compact placement policy.
In the Auto-delete section, you can enable the auto-delete option to let Compute Engine automatically delete the reservation at a specific date and time. Automatically deleting reservations can be useful to avoid unnecessary charges when you stop consuming the reservation.
To create the reservation, click Create.
The Reservations page opens. Creating the single-project reservation might take up to a minute to complete.
gcloud
To create a single-project reservation, use the
gcloud compute reservations create
command.
To create a single-project reservation by specifying properties directly and without including any optional flags, run the following command:
gcloud compute reservations create RESERVATION_NAME \
--machine-type=MACHINE_TYPE \
--vm-count=NUMBER_OF_VMS \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation to create.MACHINE_TYPE
: a machine type to use for each VM. If you specify an A3 machine type, then you must include the--require-specific-reservation
flag. This indicates that only VMs that specifically target the reservation can consume it. For more information, see Consume VMs from a specific reservation.NUMBER_OF_VMS
: the number of VMs to reserve.ZONE
: the zone in which to reserve resources.
For example, to create a reservation in zone us-central1-a
for ten VMs
that each use an N2 predefined machine type with 4 vCPUs, run the
following command:
gcloud compute reservations create my-reservation \
--machine-type=n2-standard-4 \
--vm-count=10 \
--zone=us-central1-a
Optionally, you can do one or more of the following:
To attach GPUs to your reserved N1 VMs, include the
--accelerator
flag.gcloud compute reservations create RESERVATION_NAME \ --accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE --machine-type=MACHINE_TYPE \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace the following:
NUMBER_OF_ACCELERATORS
: the number of GPUs to add per reserved VM.ACCELERATOR_TYPE
: a supported GPU model for N1 VMs. Ensure that your chosen GPU model is available in the zone where you want to reserve resources. Otherwise, creating the reservation fails.
To add one or more Local SSD disks to each reserved VM, include one or more
--local-ssd
flags. You can specify up to 24 Local SSD disks. Each Local SSD disk is 375 GB.For example, to specify two Local SSD disks when creating a reservation, include two
--local-ssd
flags as follows:gcloud compute reservations create RESERVATION_NAME \ --local-ssd=size=375,interface=INTERFACE_1 \ --local-ssd=size=375,interface=INTERFACE_2 \ --machine-type=MACHINE_TYPE \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
INTERFACE_1
andINTERFACE_2
with the type of interface you want each Local SSD disk to use. Specify one of the following values:NVME disk interfaces:
nvme
SCSI disk interfaces:
scsi
Make sure that the machine type you specify for the reserved VMs supports the chosen disk interfaces. Otherwise, creating the reservation fails. For more information, see how to choose a disk interface.
To have the reserved VMs use a specific minimum CPU platform instead of the zone's default CPU platform, include the
--min-cpu-platform
flag.gcloud compute reservations create RESERVATION_NAME \ --machine-type=MACHINE_TYPE \ --min-cpu-platform="MIN_CPU_PLATFORM" \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
MIN_CPU_PLATFORM
with a minimum CPU platform. To make sure that a CPU platform is available in the zone where you're reserving resources, view the available CPU platforms by zone.To specify that only VMs that specifically target this reservation can consume it, include the
--require-specific-reservation
flag.gcloud compute reservations create RESERVATION_NAME \ --machine-type=MACHINE_TYPE \ --require-specific-reservation \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
To specify a compact placement policy for lower network latency among VMs, include the
--resource-policies=policy
flag.gcloud compute reservations create RESERVATION_NAME \ --machine-type=MACHINE_TYPE \ --resource-policies=policy=COMPACT_PLACEMENT_POLICY_NAME \ --require-specific-reservation \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace COMPACT_PLACEMENT_POLICY_NAME with the name of an existing compact placement policy. Additionally, to avoid errors when creating a single-project reservation that specifies a compact placement policy, make sure to specify the following:
A supported machine type and maximum number of VMs for compact placement policies.
A zone within the region where the compact placement policy is located.
The
--require-specific-reservation
flag. This indicates that only VMs that specifically target the reservation can consume it.
To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, use the
gcloud beta compute reservations create
command with the--reservation-sharing-policy=ALLOW_ALL
flag.gcloud beta compute reservations create RESERVATION_NAME \ --machine-type=MACHINE_TYPE \ --reservation-sharing-policy=ALLOW_ALL \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
To enable Compute Engine to automatically delete the reservation, select one of the following methods:
To delete the reservation at a specific date and time, use the
gcloud beta compute reservations create
command with the--delete-at-time
flag.gcloud beta compute reservations create RESERVATION_NAME \ --delete-at-time=DELETE_AT_TIME \ --machine-type=MACHINE_TYPE \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
DELETE_AT_TIME
with a date and time formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-
).HH:MM:SS
: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:
).OFFSET
: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the reservation after a specific duration, use the
gcloud beta compute reservations create
command with the--delete-after-duration
flag.gcloud beta compute reservations create RESERVATION_NAME \ --delete-after-duration=DELETE_AFTER_DURATION \ --machine-type=MACHINE_TYPE \ --vm-count=NUMBER_OF_VMS \ --zone=ZONE
Replace
DELETE_AFTER_DURATION
with a duration in days, hours, minutes, or seconds. For example, specify30m
for 30 minutes, or1d2h3m4s
for 1 day, 2 hours, 3 minutes, and 4 seconds.
Go
Java
Node.js
Python
Terraform
To create a single-project reservation, use the
google_compute_reservation
Terraform resource.
For example, to create a single-project reservation for one N2 predefined machine type with 2 vCPUs, use the following resource:
For more information about how to use Terraform, see Using Terraform with Google Cloud.
REST
To create a single-project reservation, make a POST
request to the
reservations.insert
method.
To create a single-project reservation by specifying properties directly and
without any including any optional fields, make the following POST
request:
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"
}
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to reserve resources.ZONE
: the zone in which to reserve resources.RESERVATION_NAME
: the name of the reservation to create.NUMBER_OF_VMS
: the number of VMs to reserve.MACHINE_TYPE
: a machine type to use for each VM. If you specify an A3 machine type, then you must include thespecificReservationRequired
field in the request body, and set the field totrue
. This indicates that only VMs that specifically target the reservation can consume it. For more information, see Consume VMs from a specific reservation.
For example, to create a reservation in zone us-central1-a
for ten VMs
that each use an N2 predefined machine type with 4 vCPUs, make the
following POST
request:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "my-reservation",
"specificReservation": {
"count": "10",
"instanceProperties": {
"machineType": "n2-standard-4",
}
}
}
Optionally, you can do one or more of the following:
To attach GPUs to your reserved N1 VMs, include the
guestAccelerators
field in the request body.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "guestAccelerators": [ { "acceleratorCount": NUMBER_OF_ACCELERATORS, "acceleratorType": "ACCELERATOR_TYPE" } ], "machineType": "MACHINE_TYPE" } } }
Replace the following:
NUMBER_OF_ACCELERATORS
: the number of GPUs to add per reserved VM.ACCELERATOR_TYPE
: a supported GPU model for N1 VMs. Ensure that your chosen GPU model is available in the zone where you want to reserve resources. Otherwise, creating the reservation fails.
To add one or more Local SSD disks to each reserved VM, include the
localSsds
field in the request body. You can specify up to 24 Local SSD disks. Each Local SSD disk is 375 GB.For example, to specify two Local SSD disks when creating a reservation, make a request as follows:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "localSsds": [ { "diskSizeGb": "375", "interface": "INTERFACE_1" }, { "diskSizeGb": "375", "interface": "INTERFACE_2" } ], "machineType": "MACHINE_TYPE" } } }
Replace
INTERFACE_1
andINTERFACE_2
with the type of interface you want each Local SSD disk to use. Specify one of the following values:NVME disk interfaces:
NVME
SCSI disk interfaces:
SCSI
Make sure that the machine type you specify for the reserved VMs supports the chosen disk interfaces. Otherwise, creating the reservation fails. For more information, see how to choose a disk interface.
To have the reserved VMs use a specific minimum CPU platform instead of the zone's default CPU platform, include the
minCpuPlatform
field in the request body.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": "MIN_CPU_PLATFORM" } } }
Replace
MIN_CPU_PLATFORM
with a minimum CPU platform. To make sure that a CPU platform is available in the zone where you're reserving resources, view the available CPU platforms by zone.To specify a compact placement policy to reduce network latency among your reserved VMs, include the
resourcePolicies
field in the request body.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "resourcePolicies": { "policy" : "projects/example-project/regions/REGION/resourcePolicies/COMPACT_PLACEMENT_POLICY_NAME" }, "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "machineType": "MACHINE_TYPE" } }, "specificReservationRequired": true }
Replace the following:
REGION
: the region where the compact placement policy is located. You can only create the reservation within the region of the placement policy.COMPACT_PLACEMENT_POLICY_NAME
: the name of an existing compact placement policy.
Additionally, to avoid errors when creating a single-project reservation that specifies a compact placement policy, make sure to specify the following:
A supported machine type for compact placement policies.
The
specificReservationRequired
field set totrue
. This indicates that only VMs that specifically target this reservation can consume it.
To specify that only VMs that specifically target this reservation can consume it, include the
specificReservationRequired
field in the request body and set the field totrue
.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" } }, "specificReservationRequired": true }
To allow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, make a
POST
request to thebeta.reservations.insert
method. In the request body, include theserviceShareType
field and set it toALLOW_ALL
.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "name": "RESERVATION_NAME", "reservationSharingPolicy": { "serviceShareType": "ALLOW_ALL" }, "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "machineType": "MACHINE_TYPE" } } }
To enable Compute Engine to automatically delete the reservation, select one of the following methods:
To delete the reservation at a specific date and time, make a
POST
request to thebeta.reservations.insert
method. In the request body, include thedeleteAtTime
field.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "deleteAtTime": "DELETE_AT_TIME", "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "machineType": "MACHINE_TYPE" } } }
Replace
DELETE_AT_TIME
with a date and time formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month, separated by hyphens (-
).HH:MM:SS
: a time formatted as a 2-digit hour using a 24-hour time, 2-digit minutes, and 2-digit seconds, separated by colons (:
).OFFSET
: the time zone formatted as an offset of Coordinated Universal Time (UTC). For example, to use the Pacific Standard Time (PST), specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the reservation after a specific duration, make a
POST
request to thebeta.reservations.insert
method. In the request body, include thedeleteAfterDuration
field.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations { "deleteAfterDuration": { "seconds": "DELETE_AFTER_DURATION" }, "name": "RESERVATION_NAME", "specificReservation": { "count": "NUMBER_OF_VMS", "instanceProperties": { "machineType": "MACHINE_TYPE" } } }
Replace
DELETE_AFTER_DURATION
with a duration in seconds. For example, specify86400
for 86,400 seconds (1 day).
Troubleshooting
Learn how to troubleshoot reservation creation.
What's next
Learn how to view your reservations.
Learn how to attach reservations to commitments.
Learn how to consume reservations.
Learn how to monitor reservations consumption.