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.
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.
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.
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.