View reservations

This document explains how to view reservations.

Viewing reservations is useful to get an overview of all the reservations in your project, or review the configuration details of a reservation. If you want to view a shared reservation, then you can only view it using the owner project.

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
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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

Based on the details that you want to view in a reservation, select one of the following methods:

To get an overview of all the reservations in your project, view a list of your reservations.
To view the configuration details of a reservation, such as the consumer 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, select one of the following options:

Console

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

Go to Reservations

On the On-demand reservations tab (default), 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

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, include the --filter flag.

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

Replace FILTER_EXPRESSION with a filter expression.

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"

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-t4",
          "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, include the filter query parameter as follows:

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, select one of the following options:

Console

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

Go to Reservations
On the On-demand reservations tab (default), in the Name column, click the name of the reservation that you want to view the details of.

The details page of the reservation opens. To determine the utilization of a reservation, see Total Machines Reserved and Machines used.

gcloud

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

gcloud compute reservations describe RESERVATION_NAME \
    --zone=ZONE

Replace the following:

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

The output is similar to the following:

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-t4
    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 is similar to the following:

{
  "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-t4",
          "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.