This document explains how to create single-project future reservation requests.
If Google Cloud approves your single-project future reservation request, then, at the start time specified in your request, Compute Engine automatically creates reservations that can only be consumed by virtual machine (VM) instances created in the same project.
Before you begin
- If you haven't already, review how future reservations work.
- To make sure that you have sufficient quota for the resources that you want to reserve, check your quota.
-
If you haven't already, 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 as follows.
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.
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 future reservation requests,
ask your administrator to grant you the
Compute Future Reservation User (roles/compute.futureReservationUser
) 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 future reservation requests. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create single-project future reservation requests:
-
To create a future reservation request:
compute.futureReservations.create
on the project -
To let Compute Engine auto-create 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 future reservation request
This section explains how to create a single-project future reservation request.
To consume an auto-created reservation for a future reservation, a VM must have properties that exactly match that reservation. To specify the properties of the VMs that you want to request to reserve by creating a future reservation request, select one of the following methods:
Recommended: Specify an instance template
This section explains how you can use an existing instance template to define the properties of a future reservation request. By using an instance template, you can define the properties of a future reservation and the VMs that can consume the auto-created reservations in the same place.
-
This section explains how to directly define the properties of a future reservation request. This method requires you to manually ensure that the properties of your VMs and the auto-created reservations match exactly—any mismatched properties prevent consumption.
An auto-created reservation for a future reservation can be automatically consumed by any VMs with matching properties. If you want to avoid a VM to consume any of these auto-created reservations, see how to create VMs without consuming reservations.
Specify an instance template
You can create a single-project future reservation by specifying an existing instance template using the Google Cloud console, gcloud CLI, and REST.
Console
To create a single-project future reservation request by specifying an instance template, follow these steps:
In the Google Cloud console, go to the Reservations page.
Click the Future reservations tab.
Click
Create future reservation.The Create a future reservation page opens.
In the Name field, enter a name for your future reservation request.
In the Prefix field, enter a name prefix. The name of each auto-created reservation from this future reservation request starts with this prefix.
To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.
Optional: In the Description field, enter a description for your future reservation request.
In the Region field, select the region to reserve resources in.
In the Zone field, select the zone to reserve resources in.
In the Start time field, enter a start time for the reservation period. The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review.
Make sure to specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
In the End time field, enter an end time for the reservation period. The reservation period must last at least 24 hours.
In the Duration summary section, you can see the length of the reservation period. To increase the likelihood that Google Cloud approves your future reservation request after submitting it for review, make sure to specify a recommended value for the reservation period.
In the Share type section, select Local (default).
In the Number of VM instances field, enter the total count of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.
When calculating the amount of new reservations to create for an approved future reservation request shortly before the start time, Compute Engine subtracts any existing reservations that match the request from this total. For more information, see how Compute Engine counts and provisions reserved resources.
In the Machine configuration section, do the following:
To specify the properties of your VMs using 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, you can only reserve resources within the region where the instance template is located.
In the Auto-generated reservations auto-delete time section, do one of the following:
To enable Compute Engine to automatically delete the auto-created reservations for your future reservation request, do the following:
Click the Enable auto-delete toggle to the on position (default).
Optional: In the Auto-delete time field, enter a new date and time when to delete the auto-created reservations. The date and time must be after the end time of the reservation period. If you leave this field empty, the auto-created reservations are deleted within 2 hours after the end time of the reservation period.
Otherwise, click the Enable auto-delete toggle to the off position.
Do one of the following:
To create a future reservation request and submit it for review to Google Cloud, click Submit.
To create a drafting future reservation request, click Save draft.
To exit without saving, click Cancel.
The Reservations page opens. Creating the future reservation request can take up to a minute to complete.
gcloud
To create a
single-project
future reservation request by specifying
an instance template, use the
gcloud beta compute future-reservations create
command
with the --source-instance-template
flag.
gcloud beta compute future-reservations create FUTURE_RESERVATION_NAME \
--auto-delete-auto-created-reservations \
--description="DESCRIPTION" \
--name-prefix=NAME_PREFIX \
--planning-status=PLANNING_STATUS \
--project=PROJECT_ID \
--source-instance-template=projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of the future reservation request to create.
DESCRIPTION
: Optional. A description for the future reservation request.
NAME_PREFIX
: the name prefix of the future reservation request. The name of each auto-created reservation for this future reservation request starts with the name prefix. To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.PLANNING_STATUS
: Optional. The planning status of the future reservation request, which must be one of the following:To create the draft of a future reservation request, specify
DRAFT
.To create the future reservation request and submit it for approval to Google Cloud, specify
SUBMITTED
.
If you omit the
--planning-status
flag, its value is set toDRAFT
.PROJECT_ID
: the ID of the project where you want to reserve resources and where the instance template is located.
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, you can only reserve VMs within the region where the instance template is located.
INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. If you specify an instance template, you can't override its properties when creating the future reservation request. Otherwise, you encounter errors.
START_TIME
: the start time of the reservation period formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a data 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
.
The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review. To have sufficient time to optionally cancel, delete, or modify a future reservation request after it's approved or before it enters its lock time, make sure to specify a recommended value for the start time.
END_TIME
: the end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace the--end-time
flag with the--duration=END_DURATION
flag whereEND_DURATION
is the duration of the reservation period in seconds. For example, specify1209600
for 1,209,600 seconds (14 days).To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, make sure to specify one of the recommended values for your reservation period.
TOTAL_COUNT
: the total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.When calculating the number of reservations to create for an approved future reservation, Compute Engine first checks for existing reservations. If there are existing reservations that match the approved future reservation, the number of existing reservations is subtracted from the requested total number of reservations in the request to determine the number of new reservations that Compute Engine creates. For more information, see how Compute Engine counts and provisions reserved resources.
ZONE
: the zone to reserve resources in.
When you specify the --auto-delete-auto-created-reservations
flag,
Compute Engine automatically deletes the auto-created reservations for
your future reservation request. By default, the deletion time is within 2 hours
after the end time of the reservation period. Optionally, you can change this by
doing one of the following:
To delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the auto-created reservations at a specific time after the end time of the reservation period, specify the
--auto-delete-auto-created-reservations
and--auto-created-reservations-delete-time
flags.gcloud beta compute future-reservations create example-future-reservation \ --auto-delete-auto-created-reservations \ --auto-created-reservations-delete-time=AUTO_CREATED_RESERVATIONS_DELETE_TIME \ ...
Replace
AUTO_CREATED_RESERVATIONS_DELETE_TIME
with a date and time formatted as an RFC 3339 timestamp.To delete the auto-created reservations after a specific duration after the end time of the reservation period, specify the
--auto-delete-auto-created-reservations
and--auto-created-reservations-duration
flags.gcloud beta compute future-reservations create example-future-reservation \ --auto-delete-auto-created-reservations \ --auto-created-reservations-duration=DURATION_BEFORE_DELETE \ ...
Replace
DURATION_BEFORE_DELETE
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.
To disable Compute Engine from automatically deleting the auto-created reservations, specify the
--no-auto-delete-auto-created-reservations
flag. You must disable the auto-delete option if you want to attach your auto-created reservation to a commitment.gcloud beta compute future-reservations create example-future-reservation \ --no-auto-delete-auto-created-reservations \ ...
For example, the following command creates a draft future reservation request
using the example-template
global instance
template for 80 VMs.
The reservation period starts at midnight on November 10, 2023 UTC, and ends at
midnight on December 10, 2023 UTC.
The auto-created reservations for the future reservation get created in zone
us-central1-a
, have a name that starts with fr-01-reservation
,
and are automatically deleted at midnight on December 13, 2023 UTC.
gcloud beta compute future-reservations create fr-01 \
--auto-delete-auto-created-reservations \
--auto-created-reservations-delete-time=2023-12-13T00:00:00Z \
--name-prefix=fr-01-reservation \
--planning-status=DRAFT \
--project=example-project \
--source-instance-template=projects/example-project/global/instanceTemplates/example-template \
--start-time=2023-11-10T00:00:00Z \
--end-time=2023-12-10T00:00:00Z \
--total-count=80 \
--zone=us-central1-a
REST
To create a
single-project
future reservation request by specifying
an instance template,
make a POST
request to the
beta.futureReservations.insert
method.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"specificSkuProperties": {
"sourceInstanceTemplate": "projects/PROJECT_ID/LOCATION/instanceTemplates/INSTANCE_TEMPLATE_NAME",
"totalCount": "TOTAL_COUNT"
},
"timeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to reserve resources and where the instance template is located.ZONE
: the zone where you want to reserve resources.AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: if you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation request regardless if they're fully consumed or not. Set this field tofalse
if you want to attach your auto-created reservation to a commitment.By default, the deletion time is within 2 hours after the end time of the reservation period. To change this, do one of the following:
To delete the auto-created reservations after a specific time after the end of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME", ... }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes the auto-created reservations. The date and time must be formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a data 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 the Coordinated Universal Time (UTC) time zone. For example, to use the Pacific Standard Time (PST) time zone, specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDuration": { "seconds": "DURATION_BEFORE_DELETE" }, ... }
Replace
DURATION_BEFORE_DELETE
with a duration in seconds. For example, specify604800
for 604,800 seconds (7 days).
DESCRIPTION
: Optional. A description for the future reservation request.FUTURE_RESERVATION_NAME
: the name of the future reservation request to create.NAME_PREFIX
: the name prefix of the future reservation request. The name of each auto-created reservation for this future reservation request starts with the name prefix. To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.
PLANNING_STATUS
: Optional. The planning status of the future reservation request, which must be one of the following:To create the draft of a future reservation request, specify
DRAFT
.To create the future reservation request and submit it for approval to Google Cloud, specify
SUBMITTED
.
If you omit the
planningStatus
field, its value is set toDRAFT
.
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, you can only reserve VMs within the region where the instance template is located.
INSTANCE_TEMPLATE_NAME
: the name of an existing instance template. If you specify an instance template, you can't override its properties when creating the future reservation request. Otherwise, you encounter errors.
TOTAL_COUNT
: the total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.When calculating the number of reservations to create for an approved future reservation, Compute Engine first checks for existing reservations. If there are existing reservations that match the approved future reservation, the number of existing reservations is subtracted from the requested total number of reservations in the request to determine the number of new reservations that Compute Engine creates. For more information, see how Compute Engine counts and provisions reserved resources.
START_TIME
: the start time of the reservation period formatted as an RFC 3339 timestamp. The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review. Additionally, make sure to specify a recommended value for the start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: the end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace theendTime
field with theduration
field to specify a specific duration from the start time of the reservation period:"duration": { "seconds": "END_DURATION" }
Replace
END_DURATION
with a duration in seconds. For example, specify1209600
for 1,209,600 seconds (14 days).To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, make sure to specify one of the recommended values for your reservation period.
For example, the following command creates a draft future reservation request
using the example-template
global instance
template for 80 VMs.
The reservation period starts at midnight on November 10, 2023 UTC, and ends at
midnight on December 10, 2023 UTC.
The auto-created reservations for the future reservation get created in zone
us-central1-a
, have a name that starts with fr-01-reservation
,
and are automatically deleted at midnight on December 13, 2023 UTC.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations
{
"autoDeleteAutoCreatedReservations": "true",
"autoCreatedReservationsDeleteTime": "2023-12-13T00:00:00Z",
"name": "fr-01",
"namePrefix": "fr-01-reservation",
"specificSkuProperties": {
"sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-template",
"totalCount": "80"
},
"planningStatus": "DRAFT",
"timeWindow": {
"startTime": "2023-11-10T00:00:00Z",
"endTime": "2023-12-10T00:00:00Z"
}
}
Specify VM properties directly
You can create a single-project future reservation by specifying properties directly using the Google Cloud console, gcloud CLI, and REST.
Console
To create a single-project future reservation request by specifying properties directly, follow these steps:
In the Google Cloud console, go to the Reservations page.
Click the Future reservations tab.
Click
Create future reservation.The Create a future reservation page opens.
In the Name field, enter a name for your future reservation request.
In the Prefix field, enter a name prefix. The name of each auto-created reservation from this future reservation request starts with this prefix.
To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.
Optional: In the Description field, enter a description for your future reservation request.
In the Region field, select the region to reserve resources in.
In the Zone field, select the zone to reserve resources in.
In the Start time field, enter a start time for the reservation period. The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review.
Make sure to specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
In the End time field, enter an end time for the reservation period. The reservation period must last at least 24 hours.
In the Duration summary section, you can see the length of the reservation period. To increase the likelihood that Google Cloud approves your future reservation request after submitting it for review, make sure to specify a recommended value for the reservation period.
In the Share type section, select Local (default).
In the Number of VM instances field, enter the total count of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.
When calculating the amount of new reservations to create for an approved future reservation request shortly before the start time, Compute Engine subtracts any existing reservations that match the request from this total. For more information, see how Compute Engine counts and provisions reserved resources.
In the Machine configuration section, do the following:
Select Specify machine type (default).
Select one of the following options:
For common workloads, click the General purpose tab (default).
For performance-intensive workloads, click the Compute optimized tab.
For high memory-to-vCPUs ratios workloads, click the Memory optimized tab.
For workloads that use Graphics processing units (GPUs), click the GPUs tab.
Do one of the following:
If you specified General purpose, Compute optimized, or Memory optimized in the previous step, do the following:
In the Series list, select a machine series.
In the Machine type list, select a machine type.
Optional: To further customize the machine for the VMs you're requesting to reserve, expand Advanced configurations and follow the prompts.
If you specified GPUs in the previous step, do the following:
In the GPU type menu, select a type of GPU.
In the Number of GPUs menu, select the number of GPUs.
Optional: If the GPU type allows it and you want to use the reserved resources to run graphics-intensive workloads, select the Enable Virtual Workstation (NVIDIA GRID) checkbox.
In the Machine type list, select a machine type.
In the CPU platform list, select a CPU platform for the VMs you're requesting to reserve.
Optional: If the machine type allows it and you want to add local SSDs, do the following:
In the Number of disks field, select the number of disks for your local SSDs.
In the Interface type section, select one of the following interfaces:
SCSI (default)
NVMe
In the Auto-generated reservations auto-delete time section, do one of the following:
To enable Compute Engine to automatically delete the auto-created reservations for your future reservation request, do the following:
Click the Enable auto-delete toggle to the on position (default).
Optional: In the Auto-delete time field, enter a new date and time when to delete the auto-created reservations. The date and time must be after the end time of the reservation period. If you leave this field empty, the auto-created reservations are deleted within 2 hours after the end time of the reservation period.
Otherwise, click the Enable auto-delete toggle to the off position.
Do one of the following:
To create a future reservation request and submit it for review to Google Cloud, click Submit.
To create a drafting future reservation request, click Save draft.
To exit without saving, click Cancel.
The Reservations page opens. Creating the future reservation request can take up to a minute to complete.
gcloud
To create a
single-project
future reservation request by specifying
properties directly, use the
gcloud beta compute future-reservations create
command.
gcloud beta compute future-reservations create FUTURE_RESERVATION_NAME \
--accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
--auto-delete-auto-created-reservations \
--description="DESCRIPTION" \
--local-ssd=size=375,interface=INTERFACE_1 \
--local-ssd=size=375,interface=INTERFACE_2 \
--machine-type=MACHINE_TYPE \
--min-cpu-platform=MIN_CPU_PLATFORM \
--name-prefix=NAME_PREFIX \
--planning-status=PLANNING_STATUS \
--project=PROJECT_ID \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of the future reservation request to create.
Optional: To add graphics processing units (GPUs) to each reserved VM, specify the following:
NUMBER_OF_ACCELERATORS
: the number of GPUs to add per reserved VM.ACCELERATOR_TYPE
: the type of GPU to add to the reserved VMs.
Make sure that the machine type you specify in the future reservation request supports the types of GPUs you specify and that the GPU is available in the zone where you want to reserve resources. Otherwise, you encounter errors.
DESCRIPTION
: Optional. A description for the future reservation request.
INTERFACE_1
andINTERFACE_2
: Optional. The type of interface you want the local SSDs for each VM to use. The value must be one of the following:If your boot disk image has optimized NVMe drivers, specify
nvme
.Otherwise, specify
scsi
.
Each local SSD is 375 GB. Repeat the
--local-ssd
flag for each local SSD that you want to add. You can specify a maximum of 24 local SSDs.MACHINE_TYPE
: a machine type to use for each VM. Specify one of the following values:For a predefined machine type:
MACHINE_FAMILY-standard-CPUS
.For a custom machine type:
MACHINE_FAMILY-custom-CPUS-MEMORY
. Before specifying a custom machine type, review the limitations for VMs with custom machine types.
Replace the following:
MACHINE_FAMILY
: the machine family.CPUS
: the number of vCPUs.MEMORY
: the total memory for a reserved VM. Memory must be a multiple of 256 MB and must be supplied in MB.
For example, to specify an N2 custom machine type with 4 vCPUs and 5 GB of memory, which is 5,120 MB, specify
n2-custom-4-5120
.MINIMUM_CPU_PLATFORM
: Optional. The minimum CPU platform to use for each VM. If you omit the--min-cpu-platform
flag, its value is set to the zone's default CPU platform.
NAME_PREFIX
: the name prefix of the future reservation request. The name of each auto-created reservation for this future reservation request starts with the name prefix. To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.PLANNING_STATUS
: Optional. The planning status of the future reservation request, which must be one of the following:To create the draft of a future reservation request, specify
DRAFT
.To create the future reservation request and submit it for approval to Google Cloud, specify
SUBMITTED
.
If you omit the
--planning-status
flag, its value is set toDRAFT
.PROJECT_ID
: the ID of the project where you want to reserve resources.
START_TIME
: the start time of the reservation period formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a data 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
.
The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review. To have sufficient time to optionally cancel, delete, or modify a future reservation request after it's approved or before it enters its lock time, make sure to specify a recommended value for the start time.
END_TIME
: the end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace the--end-time
flag with the--duration=END_DURATION
flag whereEND_DURATION
is the duration of the reservation period in seconds. For example, specify1209600
for 1,209,600 seconds (14 days).To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, make sure to specify one of the recommended values for your reservation period.
TOTAL_COUNT
: the total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.When calculating the number of reservations to create for an approved future reservation, Compute Engine first checks for existing reservations. If there are existing reservations that match the approved future reservation, the number of existing reservations is subtracted from the requested total number of reservations in the request to determine the number of new reservations that Compute Engine creates. For more information, see how Compute Engine counts and provisions reserved resources.
ZONE
: the zone to reserve resources in.
When you specify the --auto-delete-auto-created-reservations
flag,
Compute Engine automatically deletes the auto-created reservations for
your future reservation request. By default, the deletion time is within 2 hours
after the end time of the reservation period. Optionally, you can change this by
doing one of the following:
To delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the auto-created reservations at a specific time after the end time of the reservation period, specify the
--auto-delete-auto-created-reservations
and--auto-created-reservations-delete-time
flags.gcloud beta compute future-reservations create example-future-reservation \ --auto-delete-auto-created-reservations \ --auto-created-reservations-delete-time=AUTO_CREATED_RESERVATIONS_DELETE_TIME \ ...
Replace
AUTO_CREATED_RESERVATIONS_DELETE_TIME
with a date and time formatted as an RFC 3339 timestamp.To delete the auto-created reservations after a specific duration after the end time of the reservation period, specify the
--auto-delete-auto-created-reservations
and--auto-created-reservations-duration
flags.gcloud beta compute future-reservations create example-future-reservation \ --auto-delete-auto-created-reservations \ --auto-created-reservations-duration=DURATION_BEFORE_DELETE \ ...
Replace
DURATION_BEFORE_DELETE
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.
To disable Compute Engine from automatically deleting the auto-created reservations, specify the
--no-auto-delete-auto-created-reservations
flag. You must disable the auto-delete option if you want to attach your auto-created reservation to a commitment.gcloud beta compute future-reservations create example-future-reservation \ --no-auto-delete-auto-created-reservations \ ...
For example, the following command creates a draft future reservation request
for 80 VMs.
The reservation period starts at midnight on November 10, 2023 UTC, and ends at
midnight on December 10, 2023 UTC.
The reserved VMs specify an n2-standard-4
machine type, a skylake
minimum CPU platform, and 1 local SSD with the scsi
interface and 375 GB each.
The auto-created reservations for the future reservation get created in zone
us-central1-a
, have a name that starts with fr-01-reservation
,
and are automatically deleted at midnight on December 13, 2023 UTC.
gcloud beta compute future-reservations create fr-01 \
--auto-delete-auto-created-reservations \
--auto-created-reservations-delete-time=2023-12-13T00:00:00Z \
--local-ssd=size=375,interface=scsi \
--machine-type=n2-standard-4 \
--min-cpu-platform=skylake \
--name-prefix=fr-01-reservation \
--planning-status=DRAFT \
--project=example-project \
--start-time=2023-11-10T00:00:00Z \
--end-time=2023-12-10T00:00:00Z \
--total-count=80 \
--zone=us-central1-a
REST
To create a
single-project
future reservation request by specifying
properties directly,
make a POST
request to the
beta.futureReservations.insert
method.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"specificSkuProperties": {
"instanceProperties": {
"guestAccelerators": [
{
"acceleratorCount": NUMBER_OF_ACCELERATORS,
"acceleratorType": "ACCELERATOR_TYPE"
}
],
"localSsds": [
{
"diskSizeGb": "375",
"interface": "INTERFACE_1"
},
{
"diskSizeGb": "375",
"interface": "INTERFACE_2"
}
],
"machineType": "MACHINE_TYPE",
"minCpuPlatform": "MINIMUM_CPU_PLATFORM"
},
"totalCount": "TOTAL_COUNT"
},
"timeWindow": {
"startTime": "START_TIME",
"endTime": "END_TIME"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to reserve resources.ZONE
: the zone where you want to reserve resources.AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: if you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation request regardless if they're fully consumed or not. Set this field tofalse
if you want to attach your auto-created reservation to a commitment.By default, the deletion time is within 2 hours after the end time of the reservation period. To change this, do one of the following:
To delete the auto-created reservations after a specific time after the end of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME", ... }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes the auto-created reservations. The date and time must be formatted as an RFC 3339 timestamp, which must be as follows:YYYY-MM-DDTHH:MM:SSOFFSET
Replace the following:
YYYY-MM-DD
: a data 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 the Coordinated Universal Time (UTC) time zone. For example, to use the Pacific Standard Time (PST) time zone, specify-08:00
. Alternatively, to use no offset, specifyZ
.
To delete the auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDuration": { "seconds": "DURATION_BEFORE_DELETE" }, ... }
Replace
DURATION_BEFORE_DELETE
with a duration in seconds. For example, specify604800
for 604,800 seconds (7 days).
DESCRIPTION
: Optional. A description for the future reservation request.FUTURE_RESERVATION_NAME
: the name of the future reservation request to create.NAME_PREFIX
: the name prefix of the future reservation request. The name of each auto-created reservation for this future reservation request starts with the name prefix. To help you identify the auto-created reservations for this future reservation request, specifying an unique name prefix is recommended.
PLANNING_STATUS
: Optional. The planning status of the future reservation request, which must be one of the following:To create the draft of a future reservation request, specify
DRAFT
.To create the future reservation request and submit it for approval to Google Cloud, specify
SUBMITTED
.
If you omit the
planningStatus
field, its value is set toDRAFT
.
Optional: To add graphics processing units (GPUs) to each reserved VM, specify the following:
NUMBER_OF_ACCELERATORS
: the number of GPUs to add per reserved VM.ACCELERATOR_TYPE
: the type of GPU to add to the reserved VMs.
Make sure that the machine type you specify in the future reservation request supports the types of GPUs you specify and that the GPU is available in the zone where you want to reserve resources. Otherwise, you encounter errors.
INTERFACE_1
andINTERFACE_2
: Optional. The type of interface you want the local SSDs for each VM to use. The value must be one of the following:If your boot disk image has optimized NVMe drivers, specify
NVME
.Otherwise, specify
SCSI
.
Each local SSD is 375 GB. Repeat the
--local-ssd
flag for each local SSD that you want to add. You can specify a maximum of 24 local SSDs.MACHINE_TYPE
: a machine type to use for each VM. Specify one of the following values:For a predefined machine type:
MACHINE_FAMILY-standard-CPUS
.For a custom machine type:
MACHINE_FAMILY-custom-CPUS-MEMORY
. Before specifying a custom machine type, review the limitations for VMs with custom machine types.
Replace the following:
MACHINE_FAMILY
: the machine family.CPUS
: the number of vCPUs.MEMORY
: the total memory for a reserved VM. Memory must be a multiple of 256 MB and must be supplied in MB.
For example, to specify an N2 custom machine type with 4 vCPUs and 5 GB of memory, which is 5,120 MB, specify
n2-custom-4-5120
.MINIMUM_CPU_PLATFORM
: Optional. The minimum CPU platform to use for each VM. If you omit the--min-cpu-platform
flag, its value is set to the zone's default CPU platform.
TOTAL_COUNT
: the total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request.When calculating the number of reservations to create for an approved future reservation, Compute Engine first checks for existing reservations. If there are existing reservations that match the approved future reservation, the number of existing reservations is subtracted from the requested total number of reservations in the request to determine the number of new reservations that Compute Engine creates. For more information, see how Compute Engine counts and provisions reserved resources.
START_TIME
: the start time of the reservation period formatted as an RFC 3339 timestamp. The start time can't be later than 1 year from the date and time at which you submit a future reservation request for review. Additionally, make sure to specify a recommended value for the start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: the end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace theendTime
field with theduration
field to specify a specific duration from the start time of the reservation period:"duration": { "seconds": "END_DURATION" }
Replace
END_DURATION
with a duration in seconds. For example, specify1209600
for 1,209,600 seconds (14 days).To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, make sure to specify one of the recommended values for your reservation period.
For example, the following command creates a draft future reservation request
for 80 VMs.
The reservation period starts at midnight on November 10, 2023 UTC, and ends at
midnight on December 10, 2023 UTC.
The reserved VMs specify an n2-standard-4
machine type, a skylake
minimum CPU platform, and 1 local SSD with the SCSI
interface and 375 GB each.
The auto-created reservations for the future reservation get created in zone
us-central1-a
, have a name that starts with fr-01-reservation
,
and are automatically deleted at midnight on December 13, 2023 UTC.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations
{
"autoDeleteAutoCreatedReservations": "true",
"autoCreatedReservationsDeleteTime": "2023-12-13T00:00:00Z",
"name": "fr-01",
"namePrefix": "fr-01-reservation",
"specificSkuProperties": {
"instanceProperties": {
"localSsds": [
{
"diskSizeGb": "375",
"interface": "SCSI"
}
],
"machineType": "n2-standard-4",
"minCpuPlatform": "Skylake"
},
"totalCount": "80"
},
"planningStatus": "DRAFT",
"timeWindow": {
"startTime": "2023-11-10T00:00:00Z",
"endTime": "2023-12-10T00:00:00Z"
}
}
Submit a draft future reservation request for review
You can submit a draft future reservation request to Google Cloud for review using the Google Cloud console, gcloud CLI, and REST. If you also want to modify one or more properties when submitting the draft future reservation request for review, see Modify a draft or declined future reservation request instead.
Console
To submit a draft future reservation request for review, follow these steps:
In the Google Cloud console, go to the Reservations page.
Click the Future reservations tab.
In the Name column, click the name of the a future reservation request with a procurement status of Drafting.
The Future reservations page with the details of the future reservation request opens.
Click
Edit draft.The details page of the draft future reservation request opens.
To submit the draft future reservation request for review to Google Cloud, click Submit.
The Reservation page opens. In the Status column of the future reservation request you've just submitted, the procurement status is set to Pending approval.
gcloud
To submit a draft future reservation request for review, use the
gcloud beta compute future-reservations update
command
with the --planning-status
flag set to SUBMITTED
.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--planning-status=SUBMITTED \
--project=PROJECT_ID \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing draft future reservation request.PROJECT_ID
: the ID of the project where the future reservation request is located.ZONE
: the zone where the future reservation request is located.
REST
To submit a draft future reservation request for review, make a PATCH
request to the
beta.futureReservations.update
method
with the planningStatus
field set to SUBMITTED
.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=planningStatus
{
"name": "FUTURE_RESERVATION_NAME",
"planningStatus": "SUBMITTED"
}
Replace the following:
PROJECT_ID
: the ID of the project where the future reservation request is located.ZONE
: the zone where the future reservation request is located.FUTURE_RESERVATION_NAME
: the name of an existing draft future reservation request.
After you submit a draft future reservation request for review, you can do the following:
To monitor the request's procurement status and see whether Google Cloud has approved or declined your request, then view the details of your future reservation request.
To stop Google Cloud from reviewing your request and prevent Compute Engine from provisioning the requested capacity, then cancel or delete your future reservation request.
Troubleshoot
If you run into errors when creating a future reservation request, see how to troubleshoot future reservation requests.
If you still encounter issues after troubleshooting, contact your Technical Account Manager or the Sales Team.
What's next
Learn how to view future reservation requests.
Learn how to modify, cancel, or delete future reservation requests.
After you reach the start time of your reservation period, learn how to consume the auto-created reservations.