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, 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:
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.
Terraform

To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Go

To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Java

To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Node.js

To use the Node.js samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
Python

To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
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 to projects, folders, and organizations.

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 reservations

To view information about a reservation in your project, use one of the following methods:

For an overview of all reservations in your project, view a list of your reservations.
For the full details of a specific reservation, view the details of a 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.
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"

Go

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/api/iterator"
)

// Get list of reservations for given project in particular zone
func listReservations(w io.Writer, projectID, zone string) error {
	// projectID := "your_project_id"
	// zone := "us-west3-a"

	ctx := context.Background()
	reservationsClient, err := compute.NewReservationsRESTClient(ctx)
	if err != nil {
		return err
	}
	defer reservationsClient.Close()

	req := &computepb.ListReservationsRequest{
		Project: projectID,
		Zone:    zone,
	}

	it := reservationsClient.List(ctx, req)
	fmt.Fprintf(w, "Instances found in zone %s:\n", zone)
	for {
		instance, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "- %s %d\n", instance.GetName(), instance.GetSpecificReservation().GetCount())
	}

	return nil
}

Java

import com.google.cloud.compute.v1.Reservation;
import com.google.cloud.compute.v1.ReservationsClient;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class ListReservations {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String project = "YOUR_PROJECT_ID";
    // Zone in which reservations are located.
    String zone = "us-central1-a";

    listReservations(project, zone);
  }

  // List all reservations in the given project and zone.
  public static List<Reservation> listReservations(String project, String zone) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    List<Reservation> listOfReservations = new ArrayList<>();

    try (ReservationsClient reservationsClient = ReservationsClient.create()) {
      for (Reservation reservation : reservationsClient.list(project, zone).iterateAll()) {
        listOfReservations.add(reservation);
        System.out.println("Reservation: " + reservation.getName());
      }
    }
    return listOfReservations;
  }
}

Node.js

// Import the Compute library
const computeLib = require('@google-cloud/compute');

// Instantiate a reservationsClient
const reservationsClient = new computeLib.ReservationsClient();

/**
 * TODO(developer): Update these variables before running the sample.
 */
// The ID of the project where your reservations are located.
const projectId = await reservationsClient.getProjectId();
// The zone where your reservations are located.
const zone = 'us-central1-a';

async function callGetReservations() {
  const reservations = (
    await reservationsClient.list({
      project: projectId,
      zone,
    })
  )[0];

  console.log(JSON.stringify(reservations));
}

await callGetReservations();

Python

from google.cloud import compute_v1
from google.cloud.compute_v1.services.reservations.pagers import ListPager


def list_compute_reservation(project_id: str, zone: str = "us-central1-a") -> ListPager:
    """
    Lists all compute reservations in a specified Google Cloud project and zone.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone of the reservations.
    Returns:
        ListPager: A pager object containing the list of reservations.
    """

    client = compute_v1.ReservationsClient()

    reservations_list = client.list(
        project=project_id,
        zone=zone,
    )

    for reservation in reservations_list:
        print("Name: ", reservation.name)
        print(
            "Machine type: ",
            reservation.specific_reservation.instance_properties.machine_type,
        )
    # Example response:
    # Name:  my-reservation_1
    # Machine type:  n1-standard-1
    # Name:  my-reservation_2
    # Machine type:  n1-standard-1

    return reservations_list

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:

{
  "kind": "compute#reservation",
  "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"
    },
    "count": "100",
    "inUseCount": "0",
    "assuredCount": "100"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
},
{
  "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
        }
      ],
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    },
    "count": "50",
    "inUseCount": "25",
    "assuredCount": "50"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
}

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 the details of a reservation

To see how many VMs each supported Google Cloud product is consuming in a reservation, view the details of the reservation using the Google Cloud console. Otherwise, select any 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. If you want to see the Assured count field, then you must view a list of your reservations.

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:

creationTimestamp: '2024-10-11T03:25:23.192-07:00'
id: '4488228526648280060'
kind: compute#reservation
name: r-01
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations/r-01
shareSettings:
  shareType: LOCAL
specificReservation:
  assuredCount: '50'
  count: '50'
  inUseCount: '25'
  instanceProperties:
    machineType: n2-standard-2
specificReservationRequired: false
status: READY
zone: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a

Go

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
)

// Get certain reservation for given project and zone
func getReservation(w io.Writer, projectID, zone, reservationName string) (*computepb.Reservation, error) {
	// projectID := "your_project_id"
	// zone := "us-west3-a"
	// reservationName := "your_reservation_name"

	ctx := context.Background()
	reservationsClient, err := compute.NewReservationsRESTClient(ctx)
	if err != nil {
		return nil, err
	}
	defer reservationsClient.Close()

	req := &computepb.GetReservationRequest{
		Project:     projectID,
		Reservation: reservationName,
		Zone:        zone,
	}

	reservation, err := reservationsClient.Get(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("unable to delete reservation: %w", err)
	}

	fmt.Fprintf(w, "Reservation: %s\n", reservation.GetName())

	return reservation, nil
}

Java

import com.google.cloud.compute.v1.Reservation;
import com.google.cloud.compute.v1.ReservationsClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class GetReservation {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Name of the zone in which you want to create the reservation.
    String zone = "us-central1-a";
    // Name of the reservation you want to create.
    String reservationName = "test-reservation-name";

    getReservation(projectId, reservationName, zone);
  }

  // Retrieve a reservation with the given name in the given zone.
  public static Reservation getReservation(
      String projectId, String reservationName, String zone)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (ReservationsClient reservationsClient = ReservationsClient.create()) {

      // Get the reservation.
      Reservation reservation = reservationsClient.get(projectId, zone, reservationName);

      System.out.println("Reservation: " + reservation.getName());
      return reservation;
    }
  }
}

Node.js

// Import the Compute library
const computeLib = require('@google-cloud/compute');

// Instantiate a reservationsClient
const reservationsClient = new computeLib.ReservationsClient();

/**
 * TODO(developer): Update/uncomment these variables before running the sample.
 */
// The ID of the project where your reservation is located.
const projectId = await reservationsClient.getProjectId();
// The zone where your reservation is located.
const zone = 'us-central1-a';
// The name of the reservation to return.
// reservationName = 'reservation-01';

async function callGetReservation() {
  const requestedReservation = (
    await reservationsClient.get({
      project: projectId,
      zone,
      reservation: reservationName,
    })
  )[0];

  console.log(JSON.stringify(requestedReservation));
}

await callGetReservation();

Python

from google.cloud import compute_v1
from google.cloud.compute_v1.types import compute


def get_compute_reservation(
    project_id: str,
    zone: str = "us-central1-a",
    reservation_name="your-reservation-name",
) -> compute.Reservation:
    """
    Retrieves a compute reservation from GCP.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone of the reservation.
        reservation_name (str): The name of the reservation to retrieve.
    Returns:
        compute.Reservation: The reservation object retrieved from Google Cloud.
    """

    client = compute_v1.ReservationsClient()

    reservation = client.get(
        project=project_id,
        zone=zone,
        reservation=reservation_name,
    )

    print("Name: ", reservation.name)
    print("STATUS: ", reservation.status)
    print(reservation.specific_reservation)
    # Example response:
    # Name:  your-reservation-name
    # STATUS:  READY
    # count: 3
    # instance_properties {
    #   machine_type: "n1-standard-1"
    #   local_ssds {
    #     disk_size_gb: 375
    #     interface: "NVME"
    #   }
    # ...

    return reservation

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:

{
  "kind": "compute#reservation",
  "id": "4488228526648280060",
  "creationTimestamp": "2024-10-11T03:25:23.192-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a/reservations/r-01",
  "zone": "https://www.googleapis.com/compute/v1/projects/davide-experimental/zones/us-central1-a",
  "name": "r-01",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "n2-standard-2"
    },
    "count": "50",
    "inUseCount": "25",
    "assuredCount": "50"
  },
  "specificReservationRequired": false,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  }
}

Determine the number of consumable VMs

When viewing a reservation, you can determine how many VMs are consuming the reservation, and how many more VMs can consume it, by checking the following fields:

Assured count (assuredCount): The number of VMs that are physically reserved in the reservation's zone for your project, and for any project a shared reservation is shared with.
Total count (count): The number of reserved VMs specified in the reservation. This number should match the assured count.

Caution: If a reservation's assured count is lower than its total count, then fewer VMs than expected are reserved. To resolve this issue, see Fewer VMs available for consumption.
Machines in use (inUseCount): The number of running VMs in your project, or a project a shared reservation is shared with, that are consuming the reservation.

For example, if the assured count (assuredCount) and total count (count) are both 50, and the number of VMs consuming the reservation (inUseCount) is 25, then 25 VMs are consuming the reservation, and you can create and run 25 more VMs before the reservation is fully 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.

View reservations

Before you begin

Console

gcloud

Terraform

Go

Java

Node.js

Python

REST

Required roles

Required permissions

View reservations

View a list of your reservations

Console

gcloud

Go

Java

Node.js

Python

REST

View the details of a reservation

Console

gcloud

Go

Java

Node.js

Python

REST

Determine the number of consumable VMs

What's next