This document explains how to manage future reservation requests. Specifically:
Modify a draft or submitted future reservation request to change one or more of its properties.
Cancel a future reservation request to stop Google Cloud from reviewing it or stop an approved future reservation from entering its lock time.
Delete a future reservation before it enters its required lock time or after the end of its reservation period.
If you want to manage the auto-created reservations for a fulfilled future reservation after the end of its reservation period, see instead the following:
Before you begin
-
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 modify, cancel, or delete your future reservation requests,
ask your administrator to grant you the
Compute Future Reservation Admin (roles/compute.futureReservationAdmin
) IAM role on the project.
For more information about granting roles, see Manage access.
This predefined role contains the permissions required to modify, cancel, or delete your future reservation requests. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to modify, cancel, or delete your future reservation requests:
-
To cancel a future reservation:
compute.futureReservations.cancel
on the project -
To delete a future reservation:
compute.futureReservations.delete
on the project -
To modify a future reservation:
compute.futureReservations.update
on the project
You might also be able to get these permissions with custom roles or other predefined roles.
Restrictions
In addition to the general restrictions for future reservations, when you modify, cancel, or delete a future reservation requests, the following restrictions apply:
You can only modify, cancel, or delete a future reservation request from within the project where the future reservation request was created. This lets you share a future reservation request with other projects, but users with permissions for only other projects can't modify that future reservation request.
You can only modify, cancel, or delete a future reservation request if its procurement status allows it. For details, see the following table:
Procurement status Cancel Delete Modify Drafting ( DRAFTING
)Pending approval ( PENDING_APPROVAL
)Approved ( APPROVED
)Declined ( DECLINED
)Canceled ( CANCELED
)Procuring ( PROCURING
)Provisioning ( PROVISIONING
)Fulfilled ( FULFILLED
)* Partially fulfilled ( FAILED_PARTIALLY_FULFILLED
)* Failed ( FAILED
)* * You can delete a fulfilled, partially fulfilled, or failed future reservation only after its end time.
Modify future reservation requests
You can modify a future reservation request before it reaches a procurement
status of Provisioning (PROVISIONING
) as long as it isn't canceled or pending
approval. When modifying a future reservation request, you can't change the
following properties:
For any future reservation:
The name of the future reservation.
The project where the future reservation request was created.
The zone where the future reservation is located.
For future reservation requests created by specifying an instance template:
You can't override the VM properties specified in the instance template.
You can't replace the instance template used to create a future reservation request with another template.
To modify any of these properties, you must create a new future reservation request with your desired updates.
If you want to modify other properties, select one of the following methods:
Modify a draft or declined future reservation request.
This section explains how to modify a future reservation request with a procurement status set to Drafting (
DRAFTING
) or Declined (DECLINED
).Modify an approved or procuring future reservation.
This section explains how to modify a future reservation with a procurement status set to Approved (
APPROVED
) or Procuring (PROCURING
). If you want to modify the auto-delete option, description, or name prefix of a future reservation, you can modify them without review. Otherwise, if you want to modify other properties, you need the approval of Google Cloud.
Modify a draft or declined future reservation request
If you modify a draft future reservation request, you can save your changes or submit the updated future reservation request to Google Cloud for review. If you modify a declined future reservation request instead, you must submit the request for review.
To modify the properties of a draft or declined future reservation request, select one of the following methods:
Modify a draft or declined future reservation request created by specifying an instance template.
This section explains how to modify one or more properties in a draft or declined future reservation request created by specifying an instance template. You can't modify the VM properties of a future future reservation request. Instead, you must create a new future reservation.
Modify a draft or declined future reservation request created by specifying properties directly.
This section explains how to modify one or more properties in a draft or declined future reservation request that was created by specifying properties directly.
Modify a draft or declined future reservation by specifying an instance template
For a future reservation request created by specifying an instance template with
a procurement status of Drafting (DRAFTING
) or Declined (DECLINED
), you can
modify the following properties:
Auto-delete
Description
Name prefix
Share settings
Start and end time of the reservation period
Total count (Number of VMs)
You can modify a draft or declined future reservation request that was created by specifying an instance template using the Google Cloud console, gcloud CLI, and REST.
Console
To request Google Cloud to modify a draft or declined future reservation request created by specifying an instance template, 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 future reservation request that you want to modify.
The details page of the selected future reservation request opens.
To modify the future reservation request, click
Edit or Edit draft.The page to edit the selected future reservation request opens.
Do one or more of the following:
In the Prefix field, enter a new name prefix.
In the Description field, enter a new description.
Modify the Start time or End time for your future reservation request. Make sure of the following:
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.
Specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
Specify a recommended minimum reservation period to increase the likelihood that Google Cloud approves your request after submitting it for review.
In the Share type section, you can select either Local or Shared. If you select Shared, you can add or remove projects to share the future reservation request with.
You can select up to 100 projects. These projects must be in the same organization as the project where the future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.
In the Number of VM instances 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 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.
In the Auto-generated reservations auto-delete section, you can enable or disable the automatic deletion of auto-created reservations for your future reservation request.
Optional. If you enable the auto-delete option, you can specify the date and time when Compute Engine deletes 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.
Depending on the procurement status of the future reservation request that you're modifying, do one of the following:
For a draft future reservation request, select one of the following options:
To save your changes, click Save draft.
To submit the draft future reservation request to Google Cloud for review, click Submit.
For a declined future reservation request, you can only submit it for review by clicking Submit.
If you submit a request, the Reservations page opens. Otherwise, the details page of the future reservation request opens.
gcloud
To
request Google Cloud to
modify
a draft or declined
future reservation
request
created by specifying
an instance template,
use the
gcloud beta compute future-reservations update
command.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--description="DESCRIPTION" \
--name-prefix=NAME_PREFIX \
--planning-status=PLANNING_STATUS \
--project=PROJECT_ID \
--share-setting=SHARE_SETTING \
--share-with=CONSUMER_PROJECT_IDS \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing draft or declined future reservation request.
DESCRIPTION
: Optional. A new description for the future reservation request.
NAME_PREFIX
: Optional. A new name prefix for 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
: the planning status of the future reservation request. You can only specifySUBMITTED
, which submits the future reservation request to Google Cloud for review.
PROJECT_ID
: Optional. The ID of the project where the future reservation request was created. If you modify a single-project future reservation request into a shared future reservation request, this project becomes the owner project of the future reservation request. If you omit the--project
flag, the value is set to the ID of the current project.
SHARE_SETTING
: Optional. To change the type of this future reservation request, specify one of the following values:To change a single-project future reservation request into a shared future reservation request, specify
projects
. Make sure to specify at least one consumer project using the--share-with
flag. Otherwise, modifying the future reservation fails.Otherwise, specify
local
.
CONSUMER_PROJECT_IDS
: Optional. A comma-separated list of the project IDs of projects that this future reservation request can be shared with. For example, specifyproject-1,project-2
. You can specify up to 100 projects. These projects must be in the same organization as the project where this future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.START_TIME
: Optional. The new 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 after it's approved or before it enters its lock time, make sure to specify a recommended start time.
END_TIME
: Optional. The new 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
: Optional. The new 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.
Caution: Make sure to have sufficient quota for the resources that you're requesting to reserve. Otherwise, Google Cloud declines your future reservation request.
ZONE
: the zone where the future reservation request is located.
Optionally, you can also change if and when Compute Engine automatically deletes the auto-created reservations for a future reservation request by doing one of the following:
To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the reservations within 2 hours after the end time (default), specify the
--auto-delete-auto-created-reservations
flag.gcloud beta compute future-reservations update example-future-reservation \ --auto-delete-auto-created-reservations
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 update 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 update 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.gcloud beta compute future-reservations update example-future-reservation \ --no-auto-delete-auto-created-reservations
For example, consider a draft shared future reservation request named fr-03
and located in zone us-central1-a
. Suppose that you want to modify this
shared future reservation request by making the following changes:
Convert it into a single-project future reservation request.
Disable the auto-delete option.
Reserve 100 VMs.
Submit the future reservation request to Google Cloud for approval.
To modify fr-03
, run the following command:
gcloud beta compute future-reservations update fr-03 \
--clear-share-settings \
--no-auto-delete-auto-created-reservations \
--planning-status=SUBMITTED \
--project=example-project \
--total-count=100 \
--zone=us-central1-a
REST
To
request Google Cloud to
modify
a draft or declined
future reservation
request
created by specifying
an instance template,
make a PATCH
request to the
beta.futureReservations.update
method.
In the updateMask
query parameter, specify each field that you want to update.
If you need to delete an optional field from your reservation, then include that
field in the updateMask
query parameter and omit that field from the request
body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"shareSettings": {
"projects": [
"CONSUMER_PROJECT_ID_1",
"CONSUMER_PROJECT_ID_2"
],
"shareType": "SHARE_TYPE"
},
"specificSkuProperties": {
"totalCount": "TOTAL_COUNT"
},
"timeWindow": {
"endTime": "END_TIME",
"startTime": "START_TIME"
}
}
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 or declined future reservation request. You can't modify the name of a future reservation request.UPDATE_FIELDS
: a comma-separated list of fields to update in thisPATCH
request. You must encode each comma as%2C
. For example, if you want to update theautoDeleteAutoCreatedReservations
,totalCount
, andendTime
fields in your future reservation request, specify the following:autoDeleteAutoCreatedReservations%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: Optional. If you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation reservation request. 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 at a specific time after the end time of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME" }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes 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 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 auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration { "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. To update the description for this future reservation request, do one of the following:To add or update a description, specify a description.
To remove the description, delete the
description
field from the request body and specify it inUPDATE_FIELDS
.
NAME_PREFIX
: Optional. A new name prefix for 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, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation request. You can only specifySUBMITTED
, which submits the future reservation request to Google Cloud for review.SHARE_TYPE
: Optional. To change the share type of this future reservation request, specify one of the following values:To change a single-project future reservation request into a shared future reservation request, specify
SPECIFIC_PROJECTS
. Additionally, you must specify at least one consumer project in theprojects
field. Otherwise, modifying the future reservation request fails.Otherwise, specify
LOCAL
. Additionally, you must delete theprojects
field from the request body and specify it inUPDATE_FIELDS
. Otherwise, modifying the future reservation request fails.
CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: Optional. The project IDs of projects that a shared future reservation request can be shared with. You can specify up to 100 projects. These projects must be in the same organization as the project where the future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.
TOTAL_COUNT
: Optional. The new 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
: Optional. The new 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 start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: Optional. The new 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, consider a draft shared future reservation request named fr-03
and located in zone us-central1-a
. Suppose that you want to modify this
shared future reservation request by making the following changes:
Convert it into a single-project future reservation request.
Disable the auto-delete option.
Reserve 100 VMs.
Submit the future reservation request to Google Cloud for approval.
To modify fr-03
, make the following PATCH
request:
PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-03?updateMask=autoDeleteAutoCreatedReservations%2CplanningStatus%2CshareSettings.shareType%2CspecificSkuProperties.totalCount
{
"autoDeleteAutoCreatedReservations": "false",
"name": "fr-03",
"planningStatus": "SUBMITTED",
"shareSettings": {
"shareType": "LOCAL"
},
"specificSkuProperties": {
"totalCount": "100"
}
}
After you submit a future reservation request to Google Cloud for review, view its details to monitor its procurement status.
Modify a draft or declined future reservation by specifying properties directly
For a future reservation request created by properties directly with a
procurement status set to Drafting (DRAFTING
) or Declined (DECLINED
), you
can modify the following properties:
Auto-delete
Description
Name prefix
GPUs
Local SSDs and the disk interface type
Machine series and machine type
Minimum CPU platform
Share settings
Start and end time of the reservation period
Total count (Number of VMs)
You can modify a draft or declined future reservation request that was created by specifying properties directly using the Google Cloud console, gcloud CLI, and REST.
Console
To request Google Cloud to modify a draft or declined future reservation request created by specifying properties directly, 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 future reservation request that you want to modify.
The details page of the selected future reservation request opens.
To modify the future reservation request, click
Edit or Edit draft.The page to edit the selected future reservation request opens.
Do one or more of the following:
In the Prefix field, enter a new name prefix.
In the Description field, enter a new description.
Modify the Start time or End time for your future reservation request. Make sure of the following:
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.
Specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
Specify a recommended minimum reservation period to increase the likelihood that Google Cloud approves your request after submitting it for review.
In the Share type section, you can select either Local or Shared. If you select Shared, you can add or remove projects to share the future reservation request with.
You can select up to 100 projects. These projects must be in the same organization as the project where the future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.
In the Number of VM instances 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 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.
In the Machine configuration section, you can change the following:
The machine series and machine type used in the reserved VMs.
The GPUs to attach to the reserved VMs.
The Local SSDs and the disk interface type of the reserved VMs.
Depending on the procurement status of the future reservation request that you're modifying, do one of the following:
For a draft future reservation request, select one of the following options:
To save your changes, click Save draft.
To submit the draft future reservation request to Google Cloud for review, click Submit.
For a declined future reservation request, you can only submit it for review by clicking Submit.
If you submit a request, the Reservations page opens. Otherwise, the details page of the future reservation request opens.
gcloud
To
request Google Cloud to
modify
a draft or declined
future reservation
request
created by specifying properties directly,
use the
gcloud beta compute future-reservations update
command.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
--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 \
--share-setting=SHARE_SETTING \
--share-with=CONSUMER_PROJECT_IDS \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing draft or declined future reservation request.
Optional. Do one of the following:
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.
To remove all GPUs from this future reservation request, replace the
--accelerator
flag with the--clear-accelerator
flag.
DESCRIPTION
: Optional. A new description for the future reservation request.
Optional. Do one of the following:
To add or edit the type of interface you want the local SSDs for each VM to use, replace the
INTERFACE_1
andINTERFACE_2
. 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.To remove all local SSDs from this future request reservation, remove all
--local-ssd
flags and specify the--clear-local-ssd
flag.
MACHINE_TYPE
: Optional. A predefined or custom machine type to use for each VM. Before specifying a custom machine type, review the limitations for VMs with custom machine types.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
: Optional. A new name prefix for 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
: the planning status of the future reservation request. You can only specifySUBMITTED
, which submits the future reservation request to Google Cloud for review.
PROJECT_ID
: Optional. The ID of the project where the future reservation request was created. If you modify a single-project future reservation request into a shared future reservation request, this project becomes the owner project of the future reservation request. If you omit the--project
flag, the value is set to the ID of the current project.
SHARE_SETTING
: Optional. To change the type of this future reservation request, specify one of the following values:To change a single-project future reservation request into a shared future reservation request, specify
projects
. Make sure to specify at least one consumer project using the--share-with
flag. Otherwise, modifying the future reservation fails.Otherwise, specify
local
.
CONSUMER_PROJECT_IDS
: Optional. A comma-separated list of the project IDs of projects that this future reservation request can be shared with. For example, specifyproject-1,project-2
. You can specify up to 100 projects. These projects must be in the same organization as the project where this future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.START_TIME
: Optional. The new 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 after it's approved or before it enters its lock time, make sure to specify a recommended start time.
END_TIME
: Optional. The new 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
: Optional. The new 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.
Caution: Make sure to have sufficient quota for the resources that you're requesting to reserve. Otherwise, Google Cloud declines your future reservation request.
ZONE
: the zone where the future reservation request is located.
Optionally, you can also change if and when Compute Engine automatically deletes the auto-created reservations for a future reservation request by doing one of the following:
To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the reservations within 2 hours after the end time (default), specify the
--auto-delete-auto-created-reservations
flag.gcloud beta compute future-reservations update example-future-reservation \ --auto-delete-auto-created-reservations
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 update 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 update 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.gcloud beta compute future-reservations update example-future-reservation \ --no-auto-delete-auto-created-reservations
For example, consider a draft shared future reservation request named fr-03
and located in zone us-central1-a
. Suppose that you want to modify this
shared future reservation request by making the following changes:
Convert it into a single-project future reservation request.
Disable the auto-delete option.
Reserve 100 VMs.
Submit the future reservation request to Google Cloud for approval.
To modify fr-03
, run the following command:
gcloud beta compute future-reservations update fr-03 \
--clear-share-settings \
--no-auto-delete-auto-created-reservations \
--planning-status=SUBMITTED \
--project=example-project \
--total-count=100 \
--zone=us-central1-a
REST
To
request Google Cloud to
modify
a draft or declined
future reservation
request
created by specifying properties directly,
make a PATCH
request to the
beta.futureReservations.update
method.
In the updateMask
query parameter, specify each field that you want to update.
If you need to delete an optional field from your reservation, then include that
field in the updateMask
query parameter and omit that field from the request
body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"shareSettings": {
"projects": [
"CONSUMER_PROJECT_ID_1",
"CONSUMER_PROJECT_ID_2"
],
"shareType": "SHARE_TYPE"
},
"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": {
"endTime": "END_TIME",
"startTime": "START_TIME"
}
}
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 or declined future reservation request. You can't modify the name of a future reservation request.UPDATE_FIELDS
: a comma-separated list of fields to update in thisPATCH
request. You must encode each comma as%2C
. For example, if you want to update theautoDeleteAutoCreatedReservations
,totalCount
, andendTime
fields in your future reservation request, specify the following:autoDeleteAutoCreatedReservations%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: Optional. If you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation reservation request. 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 at a specific time after the end time of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME" }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes 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 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 auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration { "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. To update the description for this future reservation request, do one of the following:To add or update a description, specify a description.
To remove the description, delete the
description
field from the request body and specify it inUPDATE_FIELDS
.
NAME_PREFIX
: Optional. A new name prefix for 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, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation request. You can only specifySUBMITTED
, which submits the future reservation request to Google Cloud for review.SHARE_TYPE
: Optional. To change the share type of this future reservation request, specify one of the following values:To change a single-project future reservation request into a shared future reservation request, specify
SPECIFIC_PROJECTS
. Additionally, you must specify at least one consumer project in theprojects
field. Otherwise, modifying the future reservation request fails.Otherwise, specify
LOCAL
. Additionally, you must delete theprojects
field from the request body and specify it inUPDATE_FIELDS
. Otherwise, modifying the future reservation request fails.
CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: Optional. The project IDs of projects that a shared future reservation request can be shared with. You can specify up to 100 projects. These projects must be in the same organization as the project where the future reservation request was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation request.
Optional. To update the graphics processing units (GPUs) attached to each reserved VM, do one of the following:
To add or modify GPUs, 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.
To remove all GPUs from this future reservation request, omit the
guestAccelerators
field in the request body and specify it inUPDATE_FIELDS
.
Optional. To update the local SSDs attached to each reserved VM, do one of the following:
To add or edit the type of interface you want the local SSDs for each VM to use, replace the
INTERFACE_1
andINTERFACE_2
. The value must be one of the following:If your boot disk image has optimized NVMe drivers, specify
NVME
.Otherwise, specify
SCSI
.
Repeat the
diskSizeGb
andinterface
fields for each local SSD that you want to add or update. You can specify a maximum of 24 local SSDs.To remove all local SSDs from this future request reservation, delete the
localSsds
field from the request body and specify it inUPDATE_FIELDS
.
MACHINE_TYPE
: Optional. A predefined or custom machine type to use for each VM. Before specifying a custom machine type, review the limitations for VMs with custom machine types.MINIMUM_CPU_PLATFORM
: Optional. To update the minimum CPU platform to use for each VM, do one of the following:To add or update the minimum CPU platform, specify a minimum CPU platform.
To revert back to the zone's default CPU platform, delete the
minCpuPlatform
field from the request body and specify it inUPDATE_FIELDS
.
TOTAL_COUNT
: Optional. The new 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
: Optional. The new 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 start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: Optional. The new 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, consider a draft shared future reservation request named fr-03
and located in zone us-central1-a
. Suppose that you want to modify this
shared future reservation request by making the following changes:
Convert it into a single-project future reservation request.
Disable the auto-delete option.
Reserve 100 VMs.
Submit the future reservation request to Google Cloud for approval.
To modify fr-03
, make the following PATCH
request:
PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-03?updateMask=autoDeleteAutoCreatedReservations%2CplanningStatus%2CshareSettings.shareType%2CspecificSkuProperties.totalCount
{
"autoDeleteAutoCreatedReservations": "false",
"name": "fr-03",
"planningStatus": "SUBMITTED",
"shareSettings": {
"shareType": "LOCAL"
},
"specificSkuProperties": {
"totalCount": "100"
}
}
After you submit a future reservation request to Google Cloud for review, view its details to monitor its procurement status.
Modify an approved or procuring future reservation
To modify the properties of an approved or procuring future reservation, select one of the following methods:
Modify an approved or procuring future reservation without review.
This section explains how to modify the auto-delete option, description, and name prefix in an approved or procuring future reservation without review. Modifying these properties is immediate, and there are no limits to the number of times you can change them until Google Cloud starts creating the reservations.
Request to modify an approved or procuring future reservation.
This section explains how to request Google Cloud to modify one or more properties in an approved or procuring future reservation. You can only submit a request to modify a future reservation with a procurement status of Procuring (
PROCURING
).
Modify an approved or procuring future reservation without review
For a future reservation with a procurement status set to Approved (APPROVED
)
or Procuring (PROCURING
), you can modify the following fields without approval
from Google Cloud:
Auto-delete
Description
Name prefix
Modifying these properties is immediate. Until the start time of a future reservation's reservation period, there are no limits to the number of times you can modify these properties.
You can modify an approved or procuring future reservation without review using the Google Cloud console, gcloud CLI, and REST.
Console
To modify an approved or procuring future reservation without 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 future reservation that you want to modify.
The details page of the selected future reservation opens.
If you want to modify the auto-delete option and description of a future reservation, do one or more of the following:
In the Auto-created reservations auto-delete time row, click
Edit, and then follow these steps: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.
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.
Click Submit.
In the Prefix row, click
Edit, and then do the following:In the Prefix field, enter a new name prefix.
Click Submit.
In the Description row, click
Edit, and then do the following:In the Description field, enter a new description.
Click Submit.
gcloud
To
modify
an approved or procuring
future reservation
without review,
use the
gcloud beta compute future-reservations update
command.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--description="DESCRIPTION" \
--name-prefix=NAME_PREFIX \
--project=PROJECT_ID \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation.
DESCRIPTION
: Optional. A new description for the future reservation.
NAME_PREFIX
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
PROJECT_ID
: Optional. The ID of the project where the future reservation was created.
ZONE
: the zone where the future reservation is located.
Optionally, you can also change if and when Compute Engine automatically deletes the auto-created reservations for a future reservation by doing one of the following:
To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the reservations within 2 hours after the end time (default), specify the
--auto-delete-auto-created-reservations
flag.gcloud beta compute future-reservations update example-future-reservation \ --auto-delete-auto-created-reservations
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 update 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 update 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.gcloud beta compute future-reservations update example-future-reservation \ --no-auto-delete-auto-created-reservations
For example, consider an approved future reservation named fr-04
and located
in zone us-central1-a
. Suppose that you want to modify this future reservation
by making the following changes:
Enable the auto-delete option.
Automatically delete the auto-created reservations after 864,000 seconds (10 days).
Specify a new name prefix.
To modify fr-04
, run the following command:
gcloud beta compute future-reservations update fr-04 \
--auto-delete-auto-created-reservations \
--auto-created-reservations-duration=864000 \
--name-prefix=new-prefix \
--project=example-project \
--zone=us-central1-a
REST
To
modify
an approved or procuring
future reservation
without review,
make a PATCH
request to the
beta.futureReservations.update
method.
In the updateMask
query parameter, specify each field that you want to update.
If you need to delete an optional field from your reservation, then include that
field in the updateMask
query parameter and omit that field from the request
body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX"
}
Replace the following:
PROJECT_ID
: the ID of the project where the future reservation is located.ZONE
: the zone where the future reservation is located.FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation. You can't modify the name of a future reservation.UPDATE_FIELDS
: a comma-separated list of fields to update in thisPATCH
request. You must encode each comma as%2C
. For example, if you want to update thedescription
andnamePrefix
fields in your future reservation, specify the following:description%2CnamePrefix
AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: Optional. If you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation reservation. 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 at a specific time after the end time of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME" }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes 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 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 auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration { "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. To update the description for this future reservation, do one of the following:To add or update a description, specify a description.
To remove the description, delete the
description
field from the request body and specify it inUPDATE_FIELDS
.
NAME_PREFIX
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
For example, consider an approved future reservation named fr-04
and located
in zone us-central1-a
. Suppose that you want to modify this future reservation
by making the following changes:
Enable the auto-delete option.
Automatically delete the auto-created reservations after 864,000 seconds (10 days).
Specify a new name prefix.
To modify fr-04
, make the following PATCH
request:
PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-04?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration%2CnamePrefix
{
"autoDeleteAutoCreatedReservations": "true",
"autoCreatedReservationsDuration": {
"seconds": "864000"
},
"name": "fr-04",
"namePrefix": "new-prefix"
}
Request to modify an approved or procuring future reservation
You can request Google Cloud to modify a future reservation with a
procurement status set to Approved (APPROVED
) or Procuring (PROCURING
) as
follows:
If you request to modify an approved future reservation, then Google Cloud does one of the following:
Approves the request and sets the procurement status to Approved (
APPROVED
). If the start time of the reservation period is within 56 days (8 weeks), Compute Engine sets the procurement status to Procuring (PROCURING
) within a few minutes.Declines the request and sets the procurement status to Declined (
DECLINED
). If you want to modify the future reservation again, see Modify a draft or declined future reservation in this document.
If you request to modify a procuring future reservation, Compute Engine creates the update status in the future reservation, and sets it to Update pending approval (
AMENDMENT_PENDING_APPROVAL
). Then, Google Cloud reviews your request and does one of the following:Approves the request and sets the update status to Update approved (
AMENDMENT_APPROVED
).Declines the request, sets the update status to Update declined (
AMENDMENT_DECLINED
), and keeps using the previously-approved properties for the auto-created reservations.
During the time Google Cloud reviews your request to modify a procuring future reservation, you can't modify any property—including the properties you can normally modify without approval—until Google Cloud approves or declines your request.
To request Google Cloud to modify the properties of an approved or procuring future reservation, select one of the following methods:
Request to modify a future reservation created by specifying an instance template.
This section explains how to request Google Cloud to modify one or more properties in an approved and submitted future reservation created by specifying an instance template. You can't replace the instance template used to create the future reservation or override its VM properties.
Request to modify a future reservation created by specifying properties directly.
This section explains how to request Google Cloud to modify one or more properties in a submitted and approved future reservation created by specifying properties directly.
Request to modify a future reservation created by specifying an instance template
For a future reservation created by specifying an instance template with a
procurement status of Approved (APPROVED
) or Procuring (PROCURING
), you can
request to modify the following properties:
Auto-delete
Description
Name prefix
Share settings
Start and end time of the reservation period
Total count (Number of VMs)†
† If you request to largely increase or decrease the total count within 14 days from the future reservation's start time, then Google Cloud is likely to decline your request.
You can request Google Cloud to modify a future reservation created by specifying an instance template using the gcloud CLI and REST.
Console
To request Google Cloud to modify an approved or procuring future reservation created by specifying an instance template, 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 future reservation that you want to modify.
The details page of the selected future reservation opens.
If you want to modify the auto-delete option and description of a future reservation, do one or more of the following:
In the Auto-created reservations auto-delete time row, click
Edit, and then follow these steps: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.
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.
Click Submit.
In the Prefix row, click
Edit, and then do the following:In the Prefix field, enter a new name prefix.
Click Submit.
In the Description row, click
Edit, and then do the following:In the Description field, enter a new description.
Click Submit.
Click
Edit.The page to edit the selected future reservation opens.
If you want to modify other properties, do one or more of the following:
Modify the Start time or End time for your future reservation. Make sure of the following:
The start time can't be later than 1 year from the date and time at which you submit a future reservation for review.
Specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
Specify a recommended minimum reservation period to increase the likelihood that Google Cloud approves your request after submitting it for review.
In the Share type section, you can select either Local or Shared. If you select Shared, you can add or remove projects to share the future reservation with.
You can select up to 100 projects. These projects must be in the same organization as the project where the future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.
In the Number of VM instances enter the total count of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation.
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.
To submit a modification request to Google Cloud for review, click Submit.
If you submit a request, the Reservations page opens. Otherwise, the details page of the future reservation opens.
gcloud
To
request Google Cloud to
modify
an approved or procuring
future reservation
created by specifying
an instance template,
use the
gcloud beta compute future-reservations update
command.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--description="DESCRIPTION" \
--name-prefix=NAME_PREFIX \
--planning-status=PLANNING_STATUS \
--project=PROJECT_ID \
--share-setting=SHARE_SETTING \
--share-with=CONSUMER_PROJECT_IDS \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation.
DESCRIPTION
: Optional. A new description for the future reservation.
NAME_PREFIX
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation. You can only specifySUBMITTED
, which submits the future reservation to Google Cloud for review.
PROJECT_ID
: Optional. The ID of the project where the future reservation was created. If you modify a single-project future reservation into a shared future reservation, this project becomes the owner project of the future reservation. If you omit the--project
flag, the value is set to the ID of the current project.
SHARE_SETTING
: Optional. To change the type of this future reservation, specify one of the following values:To change a single-project future reservation into a shared future reservation, specify
projects
. Make sure to specify at least one consumer project using the--share-with
flag. Otherwise, modifying the future reservation request fails.Otherwise, specify
local
.
CONSUMER_PROJECT_IDS
: Optional. A comma-separated list of the project IDs of projects that this future reservation can be shared with. For example, specifyproject-1,project-2
. You can specify up to 100 projects. These projects must be in the same organization as the project where this future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.START_TIME
: Optional. The new 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 for review. To have sufficient time to optionally cancel, delete, or modify a future reservation after it's approved or before it enters its lock time, make sure to specify a recommended start time.
END_TIME
: Optional. The new 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
: Optional. The new 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.
Caution: If you want to increase the number of VMs to reserve, make sure to have sufficient quota for the additional resources that you're requesting to reserve. Otherwise, Google Cloud declines your modification request.
ZONE
: the zone where the future reservation is located.
Optionally, you can also change if and when Compute Engine automatically deletes the auto-created reservations for a future reservation by doing one of the following:
To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the reservations within 2 hours after the end time (default), specify the
--auto-delete-auto-created-reservations
flag.gcloud beta compute future-reservations update example-future-reservation \ --auto-delete-auto-created-reservations
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 update 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 update 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.gcloud beta compute future-reservations update example-future-reservation \ --no-auto-delete-auto-created-reservations
For example, consider an approved future reservation named fr-05
and located
in zone us-central1-a
. Suppose that you want to to request Google Cloud
to modify this future reservation by making the following changes:
Change the end time of its reservation period to midnight of December 31, 2023 UTC.
Reserve 10 VMs.
Specify a new name prefix.
To request Google Cloud to modify fr-05
, run the following command:
gcloud beta compute future-reservations update fr-05 \
--end-time=2024-12-31T00:00:00Z \
--name-prefix=new-prefix \
--planning-status=SUBMITTED \
--project=example-project \
--total-count=10 \
--zone=us-central1-a
REST
To
request Google Cloud to
modify
an approved or procuring
future reservation
created by specifying
an instance template,
make a PATCH
request to the
beta.futureReservations.update
method.
In the updateMask
query parameter, specify each field that you want to update.
If you need to delete an optional field from your reservation, then include that
field in the updateMask
query parameter and omit that field from the request
body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"shareSettings": {
"projects": [
"CONSUMER_PROJECT_ID_1",
"CONSUMER_PROJECT_ID_2"
],
"shareType": "SHARE_TYPE"
},
"specificSkuProperties": {
"totalCount": "TOTAL_COUNT"
},
"timeWindow": {
"endTime": "END_TIME",
"startTime": "START_TIME"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where the future reservation is located.ZONE
: the zone where the future reservation is located.FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation. You can't modify the name of a future reservation.UPDATE_FIELDS
: a comma-separated list of fields to update in thisPATCH
request. You must encode each comma as%2C
. For example, if you want to update theautoDeleteAutoCreatedReservations
,totalCount
, andendTime
fields in your future reservation, specify the following:autoDeleteAutoCreatedReservations%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: Optional. If you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation reservation. 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 at a specific time after the end time of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME" }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes 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 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 auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration { "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. To update the description for this future reservation, do one of the following:To add or update a description, specify a description.
To remove the description, delete the
description
field from the request body and specify it inUPDATE_FIELDS
.
NAME_PREFIX
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation. You can only specifySUBMITTED
, which submits the future reservation to Google Cloud for review.SHARE_TYPE
: Optional. To change the share type of this future reservation, specify one of the following values:To change a single-project future reservation into a shared future reservation, specify
SPECIFIC_PROJECTS
. Additionally, you must specify at least one consumer project in theprojects
field. Otherwise, modifying the future reservation fails.Otherwise, specify
LOCAL
. Additionally, you must delete theprojects
field from the request body and specify it inUPDATE_FIELDS
. Otherwise, modifying the future reservation fails.
CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: Optional. The project IDs of projects that a shared future reservation can be shared with. You can specify up to 100 projects. These projects must be in the same organization as the project where the future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.
TOTAL_COUNT
: Optional. The new 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
: Optional. The new 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 for review. Additionally, make sure to specify a recommended start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: Optional. The new 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, consider an approved future reservation named fr-05
and located
in zone us-central1-a
. Suppose that you want to to request Google Cloud
to modify this future reservation by making the following changes:
Change the end time of its reservation period to midnight of December 31, 2023 UTC.
Reserve 10 VMs.
Specify a new name prefix.
To request Google Cloud to modify fr-05
, make the following PATCH
request:
PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-05?updateMask=namePrefix%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
{
"name": "fr-05",
"namePrefix": "new-prefix",
"planningStatus": "SUBMITTED",
"specificSkuProperties": {
"totalCount": "10"
},
"timeWindow": {
"endTime": "2023-12-31T00:00:00Z"
}
}
After you submit a request to modify a future reservation to Google Cloud, you can monitor the status of the request by viewing the details of the future reservation.
Request to modify a future reservation created by specifying properties directly
For a future reservation created by specifying properties directly with a
procurement status of Approved (APPROVED
) or Procuring (Procuring
), you can
request to modify the following properties:
Auto-delete
Description
Name prefix
GPUs‡
Local SSDs and the disk interface type‡
Machine series and machine type‡
Minimum CPU platform‡
Share settings
Start and end time of the reservation period
Total count (Number of VMs)‡
‡ If you request to change any VM properties, or largely increase or decrease the total count, within 14 days from the future reservation's start time, then Google Cloud is likely to decline your request.
You can request Google Cloud to modify a future reservation created by specifying properties directly using the Google Cloud console, gcloud CLI, and REST.
Console
To request Google Cloud to modify an approved or procuring future reservation created by specifying properties directly, 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 future reservation that you want to modify.
The details page of the selected future reservation opens.
If you want to modify the auto-delete option and description of a future reservation, do one or more of the following:
In the Auto-created reservations auto-delete time row, click
Edit, and then follow these steps: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.
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.
Click Submit.
In the Prefix row, click
Edit, and then do the following:In the Prefix field, enter a new name prefix.
Click Submit.
In the Description row, click
Edit, and then do the following:In the Description field, enter a new description.
Click Submit.
Click
Edit.The page to edit the selected future reservation opens.
If you want to modify other properties, do one or more of the following:
Modify the Start time or End time for your future reservation. Make sure of the following:
The start time can't be later than 1 year from the date and time at which you submit a future reservation for review.
Specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.
Specify a recommended minimum reservation period to increase the likelihood that Google Cloud approves your request after submitting it for review.
In the Share type section, you can select either Local or Shared. If you select Shared, you can add or remove projects to share the future reservation with.
You can select up to 100 projects. These projects must be in the same organization as the project where the future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.
In the Number of VM instances enter the total count of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation.
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.
In the Machine configuration section, you can change the following:
The machine series and machine type used in the reserved VMs.
The GPUs to attach to the reserved VMs.
The Local SSDs and the disk interface type of the reserved VMs.
To submit a modification request to Google Cloud for review, click Submit.
If you submit a request, the Reservations page opens. Otherwise, the details page of the future reservation opens.
gcloud
To
request Google Cloud to
modify
an approved or procuring
future reservation
created by specifying properties directly,
use the
gcloud beta compute future-reservations update
command.
gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
--accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
--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 \
--share-setting=SHARE_SETTING \
--share-with=CONSUMER_PROJECT_IDS \
--start-time=START_TIME \
--end-time=END_TIME \
--total-count=TOTAL_COUNT \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation.
Optional. Do one of the following:
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 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.
To remove all GPUs from this futurerequest, replace the
--accelerator
flag with the--clear-accelerator
flag.
DESCRIPTION
: Optional. A new description for the future reservation.
Optional. Do one of the following:
To add or edit the type of interface you want the local SSDs for each VM to use, replace the
INTERFACE_1
andINTERFACE_2
. 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.To remove all local SSDs from this future reservation, remove all
--local-ssd
flags and specify the--clear-local-ssd
flag.
MACHINE_TYPE
: Optional. A predefined or custom machine type to use for each VM. Before specifying a custom machine type, review the limitations for VMs with custom machine types.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
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation. You can only specifySUBMITTED
, which submits the future reservation to Google Cloud for review.
PROJECT_ID
: Optional. The ID of the project where the future reservation was created. If you modify a single-project future reservation into a shared future reservation, this project becomes the owner project of the future reservation. If you omit the--project
flag, the value is set to the ID of the current project.
SHARE_SETTING
: Optional. To change the type of this future reservation, specify one of the following values:To change a single-project future reservation into a shared future reservation, specify
projects
. Make sure to specify at least one consumer project using the--share-with
flag. Otherwise, modifying the future reservation request fails.Otherwise, specify
local
.
CONSUMER_PROJECT_IDS
: Optional. A comma-separated list of the project IDs of projects that this future reservation can be shared with. For example, specifyproject-1,project-2
. You can specify up to 100 projects. These projects must be in the same organization as the project where this future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.START_TIME
: Optional. The new 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 for review. To have sufficient time to optionally cancel, delete, or modify a future reservation after it's approved or before it enters its lock time, make sure to specify a recommended start time.
END_TIME
: Optional. The new 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
: Optional. The new 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.
Caution: If you want to increase the number of VMs to reserve, make sure to have sufficient quota for the additional resources that you're requesting to reserve. Otherwise, Google Cloud declines your modification request.
ZONE
: the zone where the future reservation is located.
Optionally, you can also change if and when Compute Engine automatically deletes the auto-created reservations for a future reservation by doing one of the following:
To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, select one of the following methods:
To delete the reservations within 2 hours after the end time (default), specify the
--auto-delete-auto-created-reservations
flag.gcloud beta compute future-reservations update example-future-reservation \ --auto-delete-auto-created-reservations
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 update 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 update 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.gcloud beta compute future-reservations update example-future-reservation \ --no-auto-delete-auto-created-reservations
For example, consider an approved future reservation named fr-05
and located
in zone us-central1-a
. Suppose that you want to to request Google Cloud
to modify this future reservation by making the following changes:
Change the end time of its reservation period to midnight of December 31, 2023 UTC.
Reserve 10 VMs.
Specify a new name prefix.
To request Google Cloud to modify fr-05
, run the following command:
gcloud beta compute future-reservations update fr-05 \
--end-time=2024-12-31T00:00:00Z \
--name-prefix=new-prefix \
--planning-status=SUBMITTED \
--project=example-project \
--total-count=10 \
--zone=us-central1-a
REST
To
request Google Cloud to
modify
an approved or procuring
future reservation
created by specifying properties directly,
make a PATCH
request to the
beta.futureReservations.update
method.
In the updateMask
query parameter, specify each field that you want to update.
If you need to delete an optional field from your reservation, then include that
field in the updateMask
query parameter and omit that field from the request
body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS
{
"autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
"description": "DESCRIPTION",
"name": "FUTURE_RESERVATION_NAME",
"namePrefix": "NAME_PREFIX",
"planningStatus": "PLANNING_STATUS",
"shareSettings": {
"projects": [
"CONSUMER_PROJECT_ID_1",
"CONSUMER_PROJECT_ID_2"
],
"shareType": "SHARE_TYPE"
},
"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": {
"endTime": "END_TIME",
"startTime": "START_TIME"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where the future reservation is located.ZONE
: the zone where the future reservation is located.FUTURE_RESERVATION_NAME
: the name of an existing approved or procuring future reservation. You can't modify the name of a future reservation.UPDATE_FIELDS
: a comma-separated list of fields to update in thisPATCH
request. You must encode each comma as%2C
. For example, if you want to update theautoDeleteAutoCreatedReservations
,totalCount
, andendTime
fields in your future reservation, specify the following:autoDeleteAutoCreatedReservations%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
AUTO_DELETE_AUTO_CREATED_RESERVATIONS
: Optional. If you set this field totrue
, Compute Engine automatically deletes the auto-created reservations for this future reservation reservation. 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 at a specific time after the end time of your reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDeleteTime
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime { "autoDeleteAutoCreatedReservations": "true", "autoCreatedReservationsDeleteTime": "DELETE_TIME" }
Replace
DELETE_TIME
with a date and time when Compute Engine deletes 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 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 auto-created reservations after a specific duration from the start time of the reservation period, set the
autoDeleteAutoCreatedReservations
totrue
and specify theautoCreatedReservationsDuration
field.PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/example-future-reservation?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration { "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. To update the description for this future reservation, do one of the following:To add or update a description, specify a description.
To remove the description, delete the
description
field from the request body and specify it inUPDATE_FIELDS
.
NAME_PREFIX
: Optional. A new name prefix for the future reservation. The name of each auto-created reservation for this future reservation starts with the name prefix. To help you identify the auto-created reservations for this future reservation, specifying an unique name prefix is recommended.
PLANNING_STATUS
: the planning status of the future reservation. You can only specifySUBMITTED
, which submits the future reservation to Google Cloud for review.SHARE_TYPE
: Optional. To change the share type of this future reservation, specify one of the following values:To change a single-project future reservation into a shared future reservation, specify
SPECIFIC_PROJECTS
. Additionally, you must specify at least one consumer project in theprojects
field. Otherwise, modifying the future reservation fails.Otherwise, specify
LOCAL
. Additionally, you must delete theprojects
field from the request body and specify it inUPDATE_FIELDS
. Otherwise, modifying the future reservation fails.
CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: Optional. The project IDs of projects that a shared future reservation can be shared with. You can specify up to 100 projects. These projects must be in the same organization as the project where the future reservation was created (the owner project). Don't specify the owner project. By default, it is already allowed to consume the shared auto-created reservations for this future reservation.
Optional. To update the graphics processing units (GPUs) attached to each reserved VM, do one of the following:
To add or modify GPUs, 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 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.
To remove all GPUs from this futurerequest, omit the
guestAccelerators
field in the request body and specify it inUPDATE_FIELDS
.
Optional. To update the local SSDs attached to each reserved VM, do one of the following:
To add or edit the type of interface you want the local SSDs for each VM to use, replace the
INTERFACE_1
andINTERFACE_2
. The value must be one of the following:If your boot disk image has optimized NVMe drivers, specify
NVME
.Otherwise, specify
SCSI
.
Repeat the
diskSizeGb
andinterface
fields for each local SSD that you want to add or update. You can specify a maximum of 24 local SSDs.To remove all local SSDs from this future reservation, delete the
localSsds
field from the request body and specify it inUPDATE_FIELDS
.
MACHINE_TYPE
: Optional. A predefined or custom machine type to use for each VM. Before specifying a custom machine type, review the limitations for VMs with custom machine types.MINIMUM_CPU_PLATFORM
: Optional. To update the minimum CPU platform to use for each VM, do one of the following:To add or update the minimum CPU platform, specify a minimum CPU platform.
To revert back to the zone's default CPU platform, delete the
minCpuPlatform
field from the request body and specify it inUPDATE_FIELDS
.
TOTAL_COUNT
: Optional. The new 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
: Optional. The new 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 for review. Additionally, make sure to specify a recommended start time to ensure that you have sufficient time before a future reservation enters its lock time.END_TIME
: Optional. The new 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, consider an approved future reservation named fr-05
and located
in zone us-central1-a
. Suppose that you want to to request Google Cloud
to modify this future reservation by making the following changes:
Change the end time of its reservation period to midnight of December 31, 2023 UTC.
Reserve 10 VMs.
Specify a new name prefix.
To request Google Cloud to modify fr-05
, make the following PATCH
request:
PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-05?updateMask=namePrefix%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
{
"name": "fr-05",
"namePrefix": "new-prefix",
"planningStatus": "SUBMITTED",
"specificSkuProperties": {
"totalCount": "10"
},
"timeWindow": {
"endTime": "2023-12-31T00:00:00Z"
}
}
After you submit a request to modify a future reservation to Google Cloud, you can monitor the status of the request by viewing the details of the future reservation.
Change any other properties in a future reservation request
If you want to change any other properties in a future reservation request
before it reaches a procurement status of Procuring (PROCURING
), follow these
steps:
Do one or more of the following:
To stop Google Cloud from reviewing the future reservation request, cancel the future reservation request.
To stop the future reservation request from restricting the type of future reservation requests that you can create in your current project—or in the projects the future reservation request is shared with—delete the future reservation request.
Create a new single-project or shared future reservation request with your desired updates.
Troubleshoot
If you run into errors when modifying a future reservation request, see how to troubleshoot future reservation requests.
If you still encounter issues after troubleshooting, contact your account representative or Google Cloud Support.
Cancel future reservation requests
You can cancel an approved, declined, or pending approval future reservation request to stop Google Cloud from provisioning the requested capacity. After you cancel a future reservation request, you can only view its details or delete it.
You can cancel a future reservation request using the gcloud CLI and REST.
gcloud
To cancel a future reservation request, use the
gcloud beta compute future-reservations cancel
command.
gcloud beta compute future-reservations cancel FUTURE_RESERVATION_NAME \
--project=PROJECT_ID \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing future reservation request.PROJECT_ID
: Optional. The ID of the project where the future reservation request is located. If you omit the--project
flag, the ID of the current project is used.ZONE
: the zone where the future reservation request is located.
REST
To cancel a future reservation request, make a POST
request to the
beta.futureReservations.cancel
method.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME/cancel
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 future reservation request.
Delete future reservation requests
You can delete a future reservation request only in one of the following cases:
The future reservation request was canceled.
Before the future reservation has reached the start time of its reservation period.
After the future reservation has reached the end time of its reservation period.
Deleting a future reservation doesn't delete the auto-created reservations for the future reservation. If you want to delete an auto-created reservation after the end of the reservation period, see Delete reservations instead.
You can delete a future reservation request using the Google Cloud console, gcloud CLI, and REST.
Console
To delete a future reservation request, follow these steps:
In the Google Cloud console, go to the Reservations page.
Click the Future reservations tab.
Select the checkbox next to each future reservation request that you want to delete.
Click
Delete reservation.To confirm, click Delete.
Deleting a future reservation request can take up to a minute to complete.
gcloud
To delete a future reservation request, use the
gcloud beta compute future-reservations delete
command.
gcloud beta compute future-reservations delete FUTURE_RESERVATION_NAME \
--project=PROJECT_ID \
--zone=ZONE
Replace the following:
FUTURE_RESERVATION_NAME
: the name of an existing future reservation request.PROJECT_ID
: Optional. The ID of the project where the future reservation request is located. If you omit the--project
flag, the ID of the current project is used.ZONE
: the zone where the future reservation request is located.
REST
To delete a future reservation request, make a DELETE
request to the
beta.futureReservations.delete
method.
DELETE https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME
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 future reservation request.
What's next
Learn how to view future reservation requests.
After you reach the start time of your reservation period, learn how to consume the auto-created reservations.
After the end time of your reservation period, learn how to do the following: