View reserved capacity

This document explains how to view reserved capacity in AI Hypercomputer. To reserve capacity in AI Hypercomputer, see Reserve capacity.

After Google Cloud approves a future reservation request, Compute Engine automatically creates (auto-creates) an empty reservation for your requested resources. You can then view the reservation to plan your workload.

At the request start time, the following occurs:

Compute Engine adds your reserved virtual machine (VM) instances to the reservation. You can then start using the reservation by creating VMs that match the reservation.
You can modify the reservation to allow Vertex AI training or prediction jobs to use it. For instructions, see Modify the sharing policy of a reservation.

Limitations

You can view a shared reservation or shared future reservation request only in the project where Google created it.

Before you begin

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

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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.

After installing the Google Cloud CLI, initialize it by running the following command:

gcloud init

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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 Future Reservation User (roles/compute.futureReservationUser) 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 the details of a future reservation request: compute.futureReservations.get 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 an auto-created reservation

To view an auto-created reservation's details and topology, do one of the following:

To plan your workload by reviewing the properties and configuration details of the reservation, view the details of a reservation.
To understand how your reserved capacity is organized for integration with your scheduler or planning tool, view the topology of a reservation.

View the details of a reservation

You can view the details of an auto-created reservation to review the requested capacity and plan your workload. This action helps you determine the following:

How many blocks of capacity are available.
How much capacity is available in each block.

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
In the On-demand reservations table, in the Name column, click the name of the reservation that you want to view the details of. A page that gives the details of the auto-created reservation appears.

gcloud

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

gcloud beta compute reservations describe RESERVATION_NAME \
    --zone=ZONE

Replace the following:

RESERVATION_NAME: the name of the auto-created reservation.
ZONE: the zone where the reservation exists.

The output is similar to the following:

creationTimestamp: '2024-10-17T12:25:02.413-07:00'
deleteAtTime: '2025-11-30T08:00:00Z'
deploymentType: DENSE
id: '9127712123172739686'
instanceTerminationAction: DELETE
kind: compute#reservation
name: example-res1
reservationSharingPolicy:
  serviceShareType: DISALLOW_ALL
resourceStatus:
  reservationBlockCount: 2
  reservationMaintenance:
    maintenanceOngoingCount: 1
    maintenancePendingCount: 0
    schedulingType: GROUPED
selfLink: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1
selfLinkWithId: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/9127712123172739686
shareSettings:
  shareType: LOCAL
specificReservation:
  assuredCount: '3'
  count: '3'
  inUseCount: '3'
  instanceProperties:
    machineType: a3-ultragpu-8g
specificReservationRequired: true
status: READY
zone: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b

REST

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

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

Replace the following:

PROJECT_ID: the ID of the project where the auto-created reservation exists.
ZONE: the zone where the reservation exists.
RESERVATION_NAME: the name of the reservation.

The output is similar to the following:

{
  "kind": "compute#reservation",
  "id": "9127712123172739686",
  "creationTimestamp": "2024-09-30T23:08:43.042-07:00",
  "selfLink": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1",
  "zone": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b",
  "name": "example-res1",
  "specificReservation": {
    "instanceProperties": {
      "machineType": "a3-ultragpu-8g"
    },
    "count": "3",
    "inUseCount": "3",
    "assuredCount": "3"
  },
  "specificReservationRequired": true,
  "status": "READY",
  "shareSettings": {
    "shareType": "LOCAL"
  },
  "resourceStatus": {
    "reservationMaintenance": {
      "schedulingType": "GROUPED"
    },
    "reservationBlockCount": 2
  },
  "reservationSharingPolicy": {
    "serviceShareType": "DISALLOW_ALL"
  },
  "deploymentType": "DENSE",
  "deleteAtTime": "2025-11-30T08:00:00Z"
}

View the topology of a reservation

You can view the detailed topology information of an auto-created reservation to help you decide where to create VMs within the reserved blocks.

To view a list of the available blocks in an auto-created reservation, select one of the following options. For a more detailed view, use the Google Cloud CLI or REST API.

Console

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

Go to Reservations
In the On-demand reservations table, 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.
In the Resource topology section, you can view information about your reserved blocks. This information includes the organization-specific ID for each block, the total number of VMs that can be deployed in the block (Count), and the number of VMs already deployed (In use).

gcloud

To view a list of the available blocks in an auto-created reservation, use the gcloud beta compute reservations blocks list command:

gcloud beta compute reservations blocks list RESERVATION_NAME \
    --zone=ZONE

Replace the following:

RESERVATION_NAME: the name of the auto-created reservation.
ZONE: the zone where the reservation exists.

The output is similar to the following:

count: 1
creationTimestamp: '2024-10-17T12:49:56.971-07:00'
id: '8544903383436022926'
inUseCount: 1
kind: compute#reservationBlock
name: example-res1-block-1
physicalTopology:
  block: c18707ac3d2493381c9f01fa775c4a68
  cluster: europe-west1-cluster-jfhb
reservationMaintenance:
  schedulingType: GROUPED
selfLink: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/example-res1-block-1
selfLinkWithId: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/8544903383436022926
status: READY
zone: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b
---
count: 2
creationTimestamp: '2024-10-17T12:49:54.354-07:00'
id: '5787689015406548144'
inUseCount: 2
kind: compute#reservationBlock
name: example-res1-block-2
physicalTopology:
  block: a9b7f2e4c6d1853902b4f5a7d8e31c60
  cluster: europe-west1-cluster-jfhb
reservationMaintenance:
  schedulingType: GROUPED
selfLink: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/example-res1-block-2
selfLinkWithId: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/5787689015406548144
status: READY
zone: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b

In the physicalTopology field of a block, you can see the physical location of the block as follows:

cluster: the global name of the cluster.
block: the organization-specific ID of the block in which VMs will be located.

REST

To view a list of the available blocks in an auto-created reservation, make a GET request to the beta reservations.reservationBlocks.get method:

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

Replace the following:

PROJECT_ID: the ID of the project where the auto-created reservation exists.
ZONE: the zone where the reservation exists.
RESERVATION_NAME: the name of the reservation.

The output is similar to the following:

{
  "items": [
    {
      "assuredCount": 1,
      "count": 1,
      "creationTimestamp": "2024-10-17T12:49:56.971-07:00",
      "id": "8544903383436022926",
      "inUseCount": 1,
      "kind": "compute#reservationBlock",
      "name": "example-res1-block-1",
      "physicalTopology": {
        "block": "c18707ac3d2493381c9f01fa775c4a68",
        "cluster": "europe-west1-cluster-jfhb"
      },
      "reservationMaintenance": {
        "schedulingType": "GROUPED"
      },
      "selfLink": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/example-res1-block-1",
      "selfLinkWithId": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/8544903383436022926",
      "status": "READY",
      "zone": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b"
    },
    {
      "assuredCount": 2,
      "count": 2,
      "creationTimestamp": "2024-10-17T12:49:54.354-07:00",
      "id": "5787689015406548144",
      "inUseCount": 2,
      "kind": "compute#reservationBlock",
      "name": "example-res1-block-2",
      "physicalTopology": {
        "block": "a9b7f2e4c6d1853902b4f5a7d8e31c60",
        "cluster": "europe-west1-cluster-jfhb"
      },
      "reservationMaintenance": {
        "schedulingType": "GROUPED"
      },
      "selfLink": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/example-res1-block-2",
      "selfLinkWithId": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1/reservationBlocks/5787689015406548144",
      "status": "READY",
      "zone": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b"
    }
  ]
}

In the physicalTopology field of a block, you can see the physical location of the block as follows:

cluster: the global name of the cluster.
block: the organization-specific ID of the block in which VMs will be located.

What's next

VM and cluster creation overview

View reserved capacity Stay organized with collections Save and categorize content based on your preferences.

Limitations

Before you begin

Console

gcloud

REST

Required roles

Required permissions

View an auto-created reservation

View the details of a reservation

Console

gcloud

REST

View the topology of a reservation

Console

gcloud

REST

What's next

View reserved capacity