Modify reservations

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, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. 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:

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

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

  2. 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.

  3. In the Auto-delete time row, click Edit auto-delete time.

  4. In the Update reservation pane, do one of the following:

    • To delete the reservation at a specific date and time, do the following:

      1. If the auto-delete option isn't already enabled, click the Enable auto-delete toggle to the on position.

      2. 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.

  5. 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, specify 30m for 30 minutes, or 1d2h3m4s 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 the beta.reservations.update method. In the request URL, include the paths query parameter set to deleteAtTime.

    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 the beta.reservations.update method. In the request URL, include the paths query parameter set to deleteAfterDuration.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, specify 86400 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

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

  2. 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.

  3. Click Edit.

  4. 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:

      1. Click Add projects.

      2. Select the checkbox for each project from the owner project's organization that you want to share the reservation with.

      3. Click Select.

  5. 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, specify project-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, specify project-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, specify project-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 the reservations.update method. In the request URL, include the paths=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 and CONSUMER_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 the reservations.update method. In the request URL, include the paths=shareSettings.projectMap.PROJECT_ID query parameter for each project that you want stop sharing the reservation with. Additionally, you must omit the shareSetting 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 and CONSUMER_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

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

  2. 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.

  3. Click Edit.

  4. In the Number of VM instances field, enter the updated number of VMs to reserve.

  5. 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

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

  2. 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.

  3. In the Share with other Google Cloud services row, click Edit service sharing settings.

  4. 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.

  5. 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:

  1. Create a new single-project or shared reservation with updated properties.

  2. 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