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
- 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.
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.
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
This section explains how to create single-project reservations.
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 directly define the properties of a reservation. This method requires you to manually ensure that the properties of your VMs and reservations match exactly—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 reservation. A compact placement policy specifies that VMs should be located as close to each other as possible to reduce network latency.
Specify an instance template
To create a single-project reservation by specifying an instance template, use the Google Cloud console, gcloud CLI, or Compute Engine API.
If you want to specify a compact placement policy in the reservation's instance template, you must use the gcloud CLI or Compute Engine API.
Console
To create a single-project reservation from an instance template, follow these steps:
In the Google Cloud console, go to the Reservations page.
The Reservations page appears.
Click
Create reservation.The Create a reservation page appears.
In the Name field, enter a name for your reservation.
Select the Region and Zone where you want to reserve resources.
In the Share type section, click Local (default).
In the Use with VM instance section, select one of the following options:
To allow matching VMs to automatically use this reservation, click Use reservation automatically (default).
To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.
In the Number of VM instances field, enter the number of VM instances 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.
To create the reservation, click Create.
Creating the single-project reservation might take some time to complete. This action redirects you to the Reservations page.
gcloud
To create a single-project reservation from an instance template, use the
gcloud compute reservations create
command
with the --source-instance-template
flag.
gcloud compute reservations create RESERVATION_NAME \
--project=PROJECT_ID \
--source-instance-template=INSTANCE_TEMPLATE_NAME \
--vm-count=NUMBER_OF_VMS \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation to create.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.INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. Learn how to create and list instance templates.NUMBER_OF_VMS
: the number of VMs to reserve.ZONE
: the zone in which to reserve resources.
If you want to indicate that only VMs that explicitly target this reservation
can use it, add the --require-specific-reservation
flag. To learn more about
targeted consumption of reservations, see
How reservations work.
For example, to create a single-project reservation from an instance template that can only be used when this reservation is specifically targeted, run the following command:
gcloud compute reservations create my-instance-template-reservation \
--project=example-project \
--source-instance-template=example-instance-template \
--vm-count=10 \
--zone=us-central1-a \
--require-specific-reservation
API
To create a single-project reservation from an instance template, make a
POST
request by using 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",
"sourceInstanceTemplate": "projects/PROJECT_ID/global/instanceTemplates/INSTANCE_TEMPLATE_NAME"
}
}
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 number of VMs to reserve.INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. Learn how to create and list instance templates.
If you want to indicate that only VMs that explicitly target this reservation
can use it, add the specificReservationRequired
field and set it to true
.
To learn more about targeted consumption of reservations, see
How reservations work.
For example, to create a single-project reservation from an instance template
that can only be used when this reservation is specifically targeted, make the
following POST
request:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "my-instance-template-reservation",
"specificReservation": {
"count": "10",
"sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-instance-template"
},
"specificReservationRequired": true
}
After you create a reservation, to see its details and if any instances have consumed the reservation, you can view the details of the reservation.
Specify properties directly
To create a single-project reservation by specifying properties directly, use the Google Cloud console, gcloud CLI, Compute Engine API, or Terraform.
If you want to specify a compact placement policy in your reservation, you must use the gcloud CLI or Compute Engine API.
Console
To create a single-project reservation, follow these steps:
In the Google Cloud console, go to the Reservations page.
The Reservations page appears.
Click
Create reservation.The Create a reservation page appears.
In the Name field, enter a name for your reservation.
Select the Region and Zone where you want to reserve resources.
In the Share type section, click Local (default).
In the Use with VM instance section, select one of the following options:
To allow matching VMs to automatically use this reservation, click Use reservation automatically (default).
To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.
In the Number of VM instances field, enter the number of VM instances that you want to reserve.
In the Machine configuration section, select Specify machine type, and then specify the following:
In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.
Optional: To specify a minimum CPU platform and/or GPUs, do the following:
To expand the CPU Platform and GPU section, click the
expander arrow.Optional: To specify a minimum CPU platform, in the CPU Platform list, select an option.
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.
Optional: To add local SSDs, do the following:
In the Number of disks field, select the number of local SSDs for each VM.
In the Interface type field, select the interface for the local SSDs.
To create the reservation, click Create.
Creating the single-project reservation might take some time to complete. This action redirects you to the Reservations page.
gcloud
To create a single-project reservation, use the
gcloud compute reservations create
command.
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
.
MINIMUM_CPU_PLATFORM
: the minimum CPU to use for each instance.NUMBER_OF_VMS
: the number of VMs 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.
If you want to indicate that only VMs that explicitly target this
reservation can use it, or if your instance template specifies a compact
placement policy, add the --require-specific-reservation
flag. To learn
more about targeted consumption of reservations, see
How reservations work.
For example, to create a reservation that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves ten N2 machines, each with 4 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=n2-standard-4 \
--vm-count=10 \
--accelerator=count=2,type=nvidia-tesla-v100 \
--local-ssd=size=375,interface=scsi \
--require-specific-reservation \
--resource-policies=policy=COMPACT_PLACEMENT_POLICY_NAME \
--zone=us-central1-a
Where COMPACT_PLACEMENT_POLICY_NAME
is the name of
an existing compact placement policy. Learn how to
create and
describe compact placement policies.
If you don't want to specify a compact placement policy in a reservation,
omit the --resource-policies
flag.
API
To create a single-project reservation, make a POST
request by using 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 VMs 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.
If you want to indicate that only VMs that explicitly target this
reservation can use it, or if your instance template specifies a compact
placement policy, add the specificReservationRequired
field and set it to
true
. To learn more about targeted consumption of reservations, see
How reservations work.
For example, to create a reservation that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves 10 N2 machines, each with 4 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": "n2-standard-4",
"minCpuPlatform": "Intel Haswell",
"guestAccelerators":
[
{
"acceleratorCount": 2,
"acceleratorType": "nvidia-tesla-v100"
}
],
"localSsds":
[
{
"diskSizeGb": "375",
"interface": "SCSI"
}
]
}
},
"resourcePolicies": {
"Placement" : "projects/my-project/regions/us-central1/resourcePolicies/COMPACT_PLACEMENT_POLICY_NAME"
},
"specificReservationRequired": true,
}
Where COMPACT_PLACEMENT_POLICY_NAME
is the name of
an existing compact placement policy. Learn how to
create and
describe compact placement policies.
If you don't want to specify a compact placement policy in a reservation,
omit the resourcePolicies
field.
Terraform
To create a single-project 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
.
For more information about how to use Terraform, see Using Terraform with Google Cloud.
After you create a reservation, to see its details and if any instances have consumed the reservation, you can view the details of the reservation.
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.