Modify reservations

This document explains how to modify a reservation.

For more information about reservations, see the following:

To read an overview of reservations, see Reservations of Compute Engine zonal resources.
To learn more about creating reservations, see the following:
- Create a reservation for a single project.
- Create a shared reservation, which can be used by multiple projects.

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the Google Cloud CLI.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.
Review the requirements and restrictions for reservations.

Modify reservations

If you want to modify a reservation, select one of the following methods specified in this document:

Resize a reservation—change the number of reserved virtual machine (VM) instances.
Add or remove consumer projects to a shared reservation—edit which projects can consume a shared reservation.
Change other properties in a reservation—change any other properties of a reservation.

Resize a reservation

You can resize a reservation to increase (upsize) or decrease (downsize) the number of reserved VMs.

If you want to upsize any reservation, the following restrictions apply:
- There must be sufficient resources in the zone where the reservation is located.
- You must have sufficient quota for the additional resources you're reserving.
If you want to downsize a specific reservation, make sure that the number of VMs in the reservation equals the number of VMs that are targeting the reservation by doing one or more of the following:
- Delete VMs.
- Update the reservationAffinity property of VMs.
Caution: Attempting to downsize a specific reservation to reserve less VMs than the number of VMs that are targeting it for consumption causes errors.

To resize the number of VMs in a reservation, use the Google Cloud console, gcloud CLI, or Compute Engine API.

Permissions required for this task

To perform this task, you must have the following permissions:

compute.reservations.resize on the reservation

Console

To resize a reservation, follow these steps:

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

Go to Reservations

The Reservations page appears.
In the Name column, click the name of the reservation you want to resize.

The details page for the reservation appears.
Click Edit.
In the Number of VM instances field, enter the updated number of VMs to reserve.
To confirm, click Save.

Resizing your reservation might take a few seconds to complete.

gcloud

To resize 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 updated number of VMs to reserve.
ZONE: the zone where the existing reservation is located.

API

To resize a reservation, make a POST request by using 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 project ID of the project that you used to create the reservation.
ZONE: the zone where the existing reservation is located.
RESERVATION_NAME: the name of an existing reservation.
NUMBER_OF_VMS: the updated number of VMs to reserve.

Add or remove consumer projects to a shared reservation

To modify the consumer projects for a shared reservation, which are the projects a shared reservation is shared with, use the Google Cloud console, gcloud CLI, or Compute Engine API.

If you want to see the consumer projects for a shared reservation, view the details of the reservation.

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), 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.

Permissions required for this task

To perform this task, you must have the following permissions:

compute.reservations.resize on the reservation in the owner project

Console

To change the consumer projects that can consume a shared reservation, follow these steps:

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

Go to Reservations

The Reservations page appears.
In the Name column, click the name of the reservation you want to describe.

The details page for the reservation appears.
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, click Add projects. In the dialog that appears, select the checkbox for each project from the owner project's organization that you want to share the reservation with. Then, click Select.
To confirm your changes, click Save.

Modifying your reservation might take a few seconds to complete.

gcloud

Using the gcloud CLI, you can change the list of projects that can consume a shared reservation by adding projects, removing projects, or replacing the entire list.

To add one or more projects to the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --add-share-with flag.
```
gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --add-share-with=CONSUMER_PROJECT_IDS
```
Replace the following:
- RESERVATION_NAME: the name of the shared reservation that you want to modify.
- ZONE: the zone where the reservation is located.
- OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
- CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of projects that you want to share this reservation with; for example project-1,project-2. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.
To remove one or more projects to the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --remove-share-with flag.
```
gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --remove-share-with=CONSUMER_PROJECT_IDS
```
Replace the following:
- RESERVATION_NAME: the name of the shared reservation that you want to modify.
- ZONE: the zone where the reservation is located.
- OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
- CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of projects that you want to stop sharing this reservation with; for example project-1,project-2. You cannot stop sharing this reservation with the OWNER_PROJECT_ID.
To replace the list of projects that can consume a shared reservation, use the gcloud compute reservations update command with the --share-with flag.
```
gcloud compute reservations update RESERVATION_NAME \
    --zone=ZONE \
    --project=OWNER_PROJECT_ID \
    --share-with=CONSUMER_PROJECT_IDS
```
Replace the following:
- RESERVATION_NAME: the name of the shared reservation that you want to modify.
- ZONE: the zone where the reservation is located.
- OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
- CONSUMER_PROJECT_IDS: a comma-separated list of one or more project IDs of all the projects that you want to allow to consume this reservation; for example project-1,project-2. Include any existing consumer project IDs that you want to continue sharing this reservation with, and omit any project IDs that you want to stop sharing this reservation with. Then, add any new consumer project IDs that you also want to share this reservation with. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

API

In the API, construct a PATCH request to the reservations.update method. In the request body, use the shareSettings.projectMap field to replace the list of projects that this reservation is shared with.

PATCH https://compute.googleapis.com/compute/v1/projects/OWNER_PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME?paths=sharedSettings.projects

{
  "shareSetting": {
    "shareType": "SPECIFIC_PROJECTS",
    "projectMap": {
      "CONSUMER_PROJECT_ID_1": {
        "projectId": "CONSUMER_PROJECT_ID_1"
      },
      "CONSUMER_PROJECT_ID_2": {
        "projectId": "CONSUMER_PROJECT_ID_2"
      }
    }
  }
}

Replace the following:

OWNER_PROJECT_ID: the project ID of the owner project, which is the project that you used to create this reservation.
ZONE: the zone where the reservation is located.
RESERVATION_NAME: the name of the reservation that you want to modify. Currently, this must be a shared reservation.
CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: the project IDs of one or more projects that you want to share this reservation with. Include any existing consumer project IDs that you want to continue sharing this reservation with, and omit any project IDs that you want to stop sharing this reservation with. Then, add any new consumer project IDs that you also want to share this reservation with. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, which is already allowed to consume this reservation by default.

Change other properties in a reservation

If you want to modify a reservation that is attached to a commitment, see instead Replace reservations that are attached to commitments.

To change any other properties of a reservation, do the following:

Create a new reservation with the desired updates.
Delete the older 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.