This document explains how to modify an existing reservation.
Modifying a reservation is useful when, for example, your capacity needs change or you want to allow or disallow projects to consume a shared reservation. If you want to modify a shared reservation, then you can only modify it using the owner project.
If you want to modify a reservation that is attached to a commitment, then see Replace reservations that are attached to commitments instead.
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 reservations,
ask your administrator to grant you the
Compute Admin (roles/compute.admin
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to modify reservations. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to modify reservations:
-
To modify the auto-delete option in a reservation or the consumer projects in a shared reservation:
compute.reservations.update
on the project -
To modify the number of VMs in a reservation:
compute.reservations.resize
on the project
You might also be able to get these permissions with custom roles or other predefined roles.
Modify reservations
Based on the properties that you want to modify in a reservation, use one of the following methods:
To enable or disable the automatic deletion of a reservation, or change the date and time when Compute Engine automatically deletes the reservation, modify the automatic deletion of a reservation.
To add or remove consumer projects that can consume a shared reservation, modify the consumer projects in a shared reservation.
To increase or decrease the number of reserved virtual machine (VM) instances in a reservation, modify the number of reserved VMs in a reservation.
To allow or disallow a reservation of A2 or A3 VMs to be consumed by custom training jobs or prediction jobs in Vertex AI, modify the sharing policy of a reservation.
If you want to change any properties that aren't mentioned in this list, then see Change other properties in a reservation in this document.
Modify the automatic deletion of a reservation
You can modify when Compute Engine automatically deletes an existing reservation by doing one of the following:
Enable the auto-delete option or change when the reservation is automatically deleted.
Disable the auto-delete option.
To modify the automatic deletion of a reservation, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), in the Name column, click the name of the reservation that you want to to modify.
The details page of the reservation opens.
In the Auto-delete time row, click
Edit auto-delete time.In the Update reservation pane, do one of the following:
To delete the reservation at a specific date and time, do the following:
If the auto-delete option isn't already enabled, click the Enable auto-delete toggle to the on position.
In the Auto-delete time field, enter a date and time when Compute Engine automatically deletes the reservation.
Otherwise, click the Enable auto-delete toggle to the off position.
Click Submit.
Modifying your reservation might take a few seconds to complete.
gcloud
When you enable the auto-delete option in a reservation, you can specify a date and time when the reservation should be deleted or specify a duration after which the reservation should be deleted.
To enable the auto-delete option or change when the reservation should be deleted, do one of the following:
To delete the reservation at a specific date and time, use the
gcloud beta compute reservations update
command with the--delete-at-time
flag.gcloud beta compute reservations update RESERVATION_NAME \ --delete-at-time=DELETE_AT_TIME \ --zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing reservation.DELETE_AT_TIME
: a date and time formatted as an RFC 3339 timestamp.ZONE
: the zone where the reservation is located.
To delete the reservation after a specific duration, use the
gcloud beta compute reservations update
command with the--delete-after-duration
flag.gcloud beta compute reservations update RESERVATION_NAME \ --delete-after-duration=DELETE_AFTER_DURATION \ --zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing reservation.DELETE_AFTER_DURATION
: a duration in days, hours, minutes, or seconds before the reservation is automatically deleted. For example, specify30m
for 30 minutes, or1d2h3m4s
for 1 day, 2 hours, 3 minutes, and 4 seconds.ZONE
: the zone where the reservation is located.
To disable the auto-delete option, use the
gcloud beta compute reservations update
command
with the --disable-auto-delete
flag.
gcloud beta compute reservations update RESERVATION_NAME \
--disable-auto-delete \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing reservation.ZONE
: the zone where the reservation is located.
REST
When you enable the auto-delete option in a reservation, you can specify a date and time when the reservation should be deleted or specify a duration after which the reservation should be deleted.
To enable the auto-delete option or change when the reservation should be deleted, do one of the following:
To delete the reservation at a specific date and time, make a
PATCH
request to thebeta.reservations.update
method. In the request URL, include thepaths
query parameter set todeleteAtTime
.PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=deleteAtTime { "name": "RESERVATION_NAME", "deleteAtTime": "DELETE_AT_TIME" }
Replace the following:
PROJECT_ID
: the ID of the project where the reservation is located.ZONE
: the zone where the reservation is located.RESERVATION_NAME
: the name of an existing reservation.DELETE_AT_TIME
: a date and time formatted as an RFC 3339 timestamp.
To delete the reservation after a specific duration, make a
PATCH
request to thebeta.reservations.update
method. In the request URL, include thepaths
query parameter set todeleteAfterDuration.seconds
.PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=deleteAfterDuration.seconds { "name": "RESERVATION_NAME", "deleteAfterDuration": { "seconds": "DELETE_AFTER_DURATION" } }
Replace the following:
PROJECT_ID
: the ID of the project where the reservation is located.ZONE
: the zone where the reservation is located.RESERVATION_NAME
: the name of an existing reservation.DELETE_AFTER_DURATION
: a duration in seconds before the reservation is automatically deleted. For example, specify86400
for 86,400 seconds (1 day).
To disable the auto-delete option, make a PATCH
request to the
beta.reservations.update
method.
In the request, specify the
paths=deleteAtTime&paths=deleteAfterDuration
query parameter and omit the
request body.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=deleteAtTime&paths=deleteAfterDuration
Replace the following:
PROJECT_ID
: the ID of the project where the reservation is located.ZONE
: the zone where the reservation is located.RESERVATION_NAME
: the name of an existing reservation.
Modify the consumer projects in a shared reservation
You can only allow projects to consume a shared reservation if these projects are located in the same organization as the owner project. To learn how to migrate a project to the owner project's organization, see Migrating projects between organization resources in the Resource Manager documentation.
After you modify which consumer projects can consume a shared reservation, the consumption of the reservation might change. For example, any removed consumer project stops consuming resources from the reservation. Additionally, if the reservation was configured to be automatically consumed by any VM that matches the reservation's properties (the default behavior), then any added consumer project might start consuming resources from the reservation. If you want to monitor a reservation's consumption, see how to verify reservations consumption.
To modify the consumer projects that can consume a shared reservation, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), in the Name column, click the name of the reservation you want to describe.
The details page for the reservation opens.
Click
Edit.In the Selected projects section, do one of the following:
To stop sharing the reservation with a specific consumer project, click
Delete.To start sharing the reservation with one or more specific projects, do the following:
Click
Add projects.Select the checkbox for each project from the owner project's organization that you want to share the reservation with.
Click Select.
To confirm your changes, click Save.
Modifying your reservation might take a few seconds to complete.
gcloud
When you modify the consumer projects for a shared reservation, you must specify a comma-separated list of IDs of projects that you want to allow, or stop allowing, to consume the shared reservation. These projects must be in the same organization as the owner project. Don't specify the owner project in the list. By default, it's already allowed to consume the shared reservation.
To modify the consumer projects for a shared reservation, select one of the following methods:
To allow one or more projects to consume a shared reservation, use the
gcloud compute reservations update
command with the--add-share-with
flag.gcloud compute reservations update RESERVATION_NAME \ --add-share-with=CONSUMER_PROJECT_IDS \ --zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing shared reservation.CONSUMER_PROJECT_IDS
: a comma-separated list of IDs of projects to share the reservation with. For example, specifyproject-1,project-2
.ZONE
: the zone where the shared reservation is located.
To stop allowing one or more projects to consume a shared reservation, use the
gcloud compute reservations update
command with the--remove-share-with
flag.gcloud compute reservations update RESERVATION_NAME \ --remove-share-with=CONSUMER_PROJECT_IDS \ --zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing shared reservation.CONSUMER_PROJECT_IDS
: a comma-separated list of IDs of projects that you want to stop sharing the reservation with. For example, specifyproject-1,project-2
.ZONE
: the zone where the shared reservation is located.
To replace the list of projects that can consume a shared reservation, use the
gcloud beta compute reservations update
command with the--share-with
flag.gcloud beta compute reservations update RESERVATION_NAME \ --share-with=CONSUMER_PROJECT_IDS \ --zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing shared reservation.ZONE
: the zone where the shared reservation is located.CONSUMER_PROJECT_IDS
: a comma-separated list of IDs of projects to share the reservation with. For example, specifyproject-1,project-2
.
REST
When you modify the consumer projects for a shared reservation, you must specify the IDs of the projects that you want to allow, or stop allowing, to consume the shared reservation. These projects must be in the same organization as the owner project. Don't specify the owner project. By default, it's already allowed to consume the shared reservation.
To modify the consumer projects for a shared reservation, select one of the following methods:
To allow one or more projects to consume a shared reservation, make a
PATCH
request to thereservations.update
method. In the request URL, include thepaths=shareSettings.projectMap.PROJECT_ID
query parameter for each project that you want to share the reservation with.For example, to allow two projects to consume a shared reservation, make the following
PATCH
request:PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=shareSettings.projectMap.CONSUMER_PROJECT_ID_1&paths=shareSettings.projectMap.CONSUMER_PROJECT_ID_2 { "name": "RESERVATION_NAME", "shareSetting": { "projectMap": { "CONSUMER_PROJECT_ID_1": { "projectId": "CONSUMER_PROJECT_ID_1" }, "CONSUMER_PROJECT_ID_2": { "projectId": "CONSUMER_PROJECT_ID_2" } } } }
Replace the following:
PROJECT_ID
: the ID of the owner project, which is the project used to create the shared reservation.ZONE
: the zone where the shared reservation is located.RESERVATION_NAME
: the name of an existing shared reservation.CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: the IDs of two projects that you want to share the reservation with.
To stop allowing one or more projects to consume a shared reservation, make a
PATCH
request to thereservations.update
method. In the request URL, include thepaths=shareSettings.projectMap.PROJECT_ID
query parameter for each project that you want stop sharing the reservation with. Additionally, you must omit theshareSetting
field from the request body.For example, to stop allowing two projects to consume a shared reservation, make the following
PATCH
request:PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=shareSettings.projectMap.CONSUMER_PROJECT_ID_1&paths=shareSettings.projectMap.CONSUMER_PROJECT_ID_2 { "name": "RESERVATION_NAME" }
Replace the following:
PROJECT_ID
: the ID of the owner project, which is the project used to create the shared reservation.ZONE
: the zone where the shared reservation is located.RESERVATION_NAME
: the name of an existing shared reservation.CONSUMER_PROJECT_ID_1
andCONSUMER_PROJECT_ID_2
: the IDs of two projects that you want to stop sharing the reservation with.
Modify the number of reserved VMs in a reservation
You can modify an existing reservation to increase or decrease the number of reserved VMs.
Before modifying the number of reserved VMs in a reservation, ensure that the following conditions are met:
If you want to increase the number of reserved VMs in a reservation, then make sure of the following:
There must be sufficient resources in the zone where the reservation is located.
You must have sufficient quota—namely, CPU and GPU quota—for the additional resources that you're reserving. To increase quota, see View and manage quotas in the Cloud Quotas documentation.
If your reservation's consumption type is specific and you want to decrease the number of reserved VMs in the reservation, then make sure that the number of VMs that are consuming the reservation doesn't exceed the size of the reservation that you want. You can do this by using the following methods:
To modify the number of reserved VMs in a reservation, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), in the Name column, click the name of the reservation that you want to modify.
The details page for the reservation opens.
Click
Edit.In the Number of VM instances field, enter the updated number of VMs to reserve.
To confirm, click Save.
Modifying your reservation might take a few seconds to complete.
gcloud
To modify the number of reserved VMs in a reservation, use the
gcloud compute reservations update
command.
gcloud compute reservations update RESERVATION_NAME \
--vm-count=NUMBER_OF_VMS \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing reservation.NUMBER_OF_VMS
: the new number of VMs to reserve.ZONE
: the zone where the reservation is located.
REST
To modify the number of reserved VMs in a reservation, make a POST
request
to the
reservations.resize
method.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME/resize
{
"specificSkuCount": "NUMBER_OF_VMS"
}
Replace the following:
PROJECT_ID
: the ID of the project where the reservation is located.ZONE
: the zone where the reservation is located.RESERVATION_NAME
: the name of an existing reservation.NUMBER_OF_VMS
: the new number of VMs to reserve.
Modify the sharing policy of a reservation
By modifying the sharing policy of a reservation of A2 or A3 VMs, you can allow or disallow custom training jobs or prediction jobs in Vertex AI to consume the reservation.
If you want to disallow Vertex AI from consuming a reservation, then, before you modify the reservation, make sure that no custom training jobs or prediction jobs are consuming the reservation. Otherwise, your jobs encounter errors.
To modify the sharing policy of a reservation of A2 or A3 VMs, select one of the following options:
Console
In the Google Cloud console, go to the Reservations page.
On the On-demand reservations tab (default), in the Name column, click the name of the reservation of A2 or A3 VMs that you want to modify.
The details page of the reservation opens.
In the Share with other Google Cloud services row, click
Edit service sharing settings.In the Reservation sharing pane, do one of the following:
To allow Vertex AI to consume the reservation, select Share reservation.
To disallow Vertex AI to consume the reservation, select Don't share reservation.
Click Save.
Modifying your reservation might take a few seconds to complete.
gcloud
To modify the sharing policy of a reservation of A2 or A3 VMs, use the
gcloud beta compute reservations update
command
with the --reservation-sharing-policy
flag.
gcloud beta compute reservations update RESERVATION_NAME \
--reservation-sharing-policy=SHARING_POLICY \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of an existing reservation.SHARING_POLICY
: the sharing policy of the reservation. Specify one of the following values:To allow Vertex AI to consume the reservation:
ALLOW_ALL
To disallow Vertex AI to consume the reservation:
DISALLOW_ALL
ZONE
: the zone where the reservation is located.
REST
To modify the sharing policy of a reservation of A2 or A3 VMs, make a
PATCH
request to the
beta.reservations.update
method.
In the request URL, include the paths
query parameter set to
reservationSharingPolicy.serviceShareType
.
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=reservationSharingPolicy.serviceShareType
{
"name": "RESERVATION_NAME",
"reservationSharingPolicy": {
"serviceShareType": "SHARING_POLICY"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where the reservation is located.ZONE
: the zone where the reservation is located.RESERVATION_NAME
: the name of an existing reservation.SHARING_POLICY
: the sharing policy of the reservation. Specify one of the following values:To allow Vertex AI to consume the reservation:
ALLOW_ALL
To disallow Vertex AI to consume the reservation:
DISALLOW_ALL
Change other properties in a reservation
If you want to modify a property that isn't mentioned in the Modify reservations section, then you must create a replacement reservation instead.
To replace a reservation without risking an unintended reduction in your reserved capacity, do the following:
Create a new single-project or shared reservation with updated properties.
If you don't need the original reservation anymore, then delete the reservation.
Troubleshoot
Learn how to troubleshoot issues with reservation updates.
What's next
Learn how to view your reservations.
Learn how to consume reservations.
Learn how to delete reservations.