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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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 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.
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.
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.