Modify reservations

This document explains how to modify reservations. To modify reservations that are attached to commitments, see Replace reservations that are attached to commitments instead.

Modify a reservation when, for example, your capacity needs change or you want to change which workloads can consume a reservation.

Limitations

Before you modify a reservation, consider the following:

  • You can only modify a shared reservation in the same project where you created it.

  • You can only modify an auto-created reservation for a future reservation after the reservation period has ended.

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:

    ConsolegcloudREST

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

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

      gcloud init
    2. Set a default region and zone.

    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:

The following permissions are required to modify reservations:

  • To modify the auto-delete option in a reservation, the consumer projects in a shared reservation, or whether Vertex AI jobs can consume a reservation of instances with attached GPUs: compute.reservations.update on the project
  • To modify the number of instances 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 change any properties that aren't mentioned in this list, you must create a new reservation. For instructions, 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 gcloud REST

  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.

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.

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, then see how to verify reservations consumption.

To modify the consumer projects that can consume a shared reservation, select one of the following options:

Console gcloud REST

  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.

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.

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 instances in a reservation

You can increase or decrease the number of reserved compute instances in a reservation. However, before you modify the number of instances, consider the following to avoid errors:

  • To increase the number of instances in any reservation, ensure the following:

  • To decrease the number of instances in a specific reservation, ensure that the number of instances that consume the reservation doesn't exceed the new, smaller number. If it does, then do one of the following with the instances in excess of the new number:

    • Delete instances

    • Stop or suspend the instances

To modify the number of reserved instances in a reservation, select one of the following options:

Console gcloud REST

  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 instances to reserve.

  5. To confirm, click Save.

    Modifying your reservation might take a few seconds to complete.

To modify the number of reserved instances 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 instances to reserve.

  • ZONE: the zone where the reservation is located.

To modify the number of reserved instances 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 instances to reserve.

Modify the sharing policy of a reservation

By modifying the sharing policy of a reservation of GPU compute instances, 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, ensure that no custom training jobs or prediction jobs are consuming the reservation. Otherwise, you encounter errors.

To modify the sharing policy of a reservation of GPU instances, select one of the following options:

Console gcloud REST

  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 GPU instances 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.

To modify the sharing policy of a reservation of GPU instances, 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.

To modify the sharing policy of a reservation of GPU instances, 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