View reservations

This document explains how to view reservations.

Before you begin

Review the requirements and restrictions for reservations.
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
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
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.

Required roles

To get the permissions that you need to view 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.

This predefined role contains the permissions required to view reservations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view reservations:

To view a list of reservations: compute.reservations.list on the project
To view the details of a reservation: compute.reservations.get on the project

You might also be able to get these permissions with custom roles or other predefined roles.

View your reservations

You can only view the reservations that were created in your current project.

Only the owner project can view a shared reservation. If you want to see the projects a shared reservation is shared with, view the details of the reservation.

View a list of your reservations

To view a list of your reservations, use the Google Cloud console, gcloud CLI, or REST.

Console

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

Go to Reservations

The Reservations page appears.

In the table, each row describes a reservation and each column describes a property. For example, the Used machines column describes the utilization and total capacity of each reservation: a value of 25 (50) represents a reservation for 50 VMs where 25 of these VMs have been consumed.

Optional: To modify which reservations and properties are displayed, use Filter and Column display options respectively.

gcloud

To view a list of your reservations, use the gcloud compute reservations list command.

gcloud compute reservations list \
    --project=PROJECT_ID

Replace PROJECT_ID with the ID of the project where your reservations are located.

The output should be similar to the following example:

NAME: r-01
IN_USE_COUNT: 0
COUNT: 5
ZONE: us-central1-a
SHARE_TYPE: LOCAL

NAME: r-02
IN_USE_COUNT: 3
COUNT: 10
ZONE: us-central1-f
SHARE_TYPE: LOCAL

Optionally, to narrow down a list of reservations using a filter expression, specify the --filter flag.

gcloud compute reservations list \
    --filter="FILTER_EXPRESSION" \
    --project=PROJECT_ID

Replace the following:

FILTER_EXPRESSION: a filter expression.
PROJECT_ID: the ID of the project where your reservations are located.

For example, to only view reservations with a name that starts with prefix and are located in zone us-central1-a, run the following command:

gcloud compute reservations list \
    --filter="name~prefix AND zone=us-central1-a" \
    --project=example-project

REST

To view a list of your reservations, make a GET request to the reservations.list method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

Replace the following:

PROJECT_ID: the ID of the project where your reservations are located.
ZONE: the zone where your reservations are located.

The output is similar to the following example:

{
  "id": "4100668622331754141",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-05",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-05",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "minCpuPlatform": "Any CPU Platform",
    },
    "count": "100",
    "inUseCount": "0"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation"
},
{
  "id": "2533514314332214789",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a",
  "name": "reservation-04",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "guestAccelerators": [
        {
          "acceleratorType": "nvidia-tesla-k80",
          "acceleratorCount": 1
        }
      ],
      "minCpuPlatform": "Any CPU Platform",
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation"
}

Optionally, to narrow down a list of reservations using a filter expression, make the following GET request:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations?filter=FILTER_EXPRESSION

Replace the following:

PROJECT_ID: the ID of the project where your reservations are located.
ZONE: the zone where your reservations are located.
FILTER_EXPRESSION: a filter expression.

For example, to only view reservations with a name that starts with prefix and are located in zone us-central1-a, make the following GET request using URL-encoded values:

GET https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations?filter=name%7Eprefix%20AND%20zone=us-central1-a

View details of a reservation

To view the details of a reservation, use the Google Cloud console, gcloud CLI, or REST.

Console

To view the details of a reservation, do the following:

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. To determine the utilization of a reservation, see the Total Machines Reserved and Machines used fields.

gcloud

To view the details of a reservation, use the gcloud compute reservations describe command.

gcloud compute reservations describe RESERVATION_NAME \
    --project=PROJECT_ID \
    --zone=ZONE

Replace the following:

RESERVATION_NAME: the name of an existing reservation.
PROJECT_ID: the ID of the project where the reservation is located.
ZONE: the zone where the reservation is located.

The output should be similar to the following example:

kind: compute#reservation
name: reservation-04
selfLink: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04
specificReservation:
  count: '50'
  inUseCount: '25'
  instanceProperties:
    guestAccelerators:
    - acceleratorCount: 1
      acceleratorType: nvidia-tesla-k80
    localSsds:
    - diskSizeGb: '375'
      interface: SCSI
    machineType: n1-standard-2
    minCpuPlatform: Any CPU Platform
specificReservationRequired: false
status: READY
zone: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

To determine the utilization of a reservation, see the count and inUseCount fields. In this example, 50 VMs are reserved and 25 VMs have been consumed.

REST

To view the details of a reservation, make a GET request to the reservations.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME

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.

The output should be similar to the following example:

{
  "id": "2533514314332214789",
  "creationTimestamp": "2019-09-27T08:21:14.707-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/reservation-04",
  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-centra1-a",
  "name": "reservation-04",
  "specificReservationRequired": false,
  "status": "READY",
  "kind": "compute#reservation",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n1-standard-2",
      "guestAccelerators": [
        {
          "acceleratorType": "nvidia-tesla-k80",
          "acceleratorCount": 1
        }
      ],
      "minCpuPlatform": "Any CPU Platform",
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25"
  }
}

To determine the utilization of a reservation, see the count and inUseCount fields. In this example, 50 VMs are reserved and 25 VMs have been consumed.

What's next

Learn how to attach reservations to commitments.
Learn how to consume reservations.
Learn how to modify reservations.
Learn how to delete reservations.