Request capacity

This document explains how to reserve blocks of capacity using future reservation requests. To learn more about how future reservation requests work, including billing and limitations, see About future reservation requests in the Compute Engine documentation.

To gain a very high assurance that your workloads have the resources they need, request a future reservation from Google. This lets you reserve blocks of capacity for a defined duration, starting on a specific date and time in the future. At your specified date and time, Compute Engine automatically provisions the blocks of capacity by automatically creating on-demand reservations that you can immediately consume by provisioning VMs. To provision single VMs or groups of VMs on these blocks, see Create VM overview.

Before you begin

Select the tab for how you plan to use the samples on this page:
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
If you want to share the reserved capacity with other projects within your organization, then enable your project to create shared reservations.

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 allow Compute Engine to auto-create reservations: compute.reservations.create on the project
To create a future reservation request: compute.futureReservations.create on the project
To specify an instance template: compute.instanceTemplates.useReadOnly on the instance template
To view the details of a future reservation request: compute.futureReservations.get on the project
To view the details of an on-demand reservation: compute.reservations.get on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

When requesting blocks of capacity using future reservation requests, the following limitations apply:

You can only request capacity for VMs using an A3 Ultra machine type with 8 GPUs (a3-ultragpu-8g).
After Google Cloud approves a future reservation request, you can't cancel or modify it. For more information about your available options, contact your assigned Technical Account Manager (TAM).
After Compute Engine automatically creates an on-demand reservation to fulfill your requested capacity, the following limitations apply:
- The auto-created reservation can include a maximum of 100 blocks of resources.
- You can only consume the auto-created reservation by specifically targeting it.
- You can't modify or delete the auto-created reservation. Compute Engine automatically deletes it at the end of the reservation period.

Overview

To request to reserve blocks of resources for Hypercompute Cluster and plan your workload, complete the following steps:

Request capacity for multiple blocks. Contact your assigned TAM to request capacity. This involves specifying the type and amount of resources that you need.
View the delivered capacity. After Google creates a future reservation request for your project, Google Cloud approves the request, and the request enters its start time, you can view the delivered capacity. This helps you plan your workload.

Request capacity for multiple blocks

To request a future reservation for multiple blocks of capacity, contact your assigned TAM and provide them the following information:

Project number: The number of the project in which your assigned TAM creates the future reservation request and Compute Engine provisions the requested capacity.
Total count: The total number of VMs using an A3 Ultra machine type with 8 GPUs that you want to reserve. You can only reserve multiples of 2 VMs.
Zone: The zone where you want to reserve the capacity. You can only reserve A3 Ultra VMs in zone europe-west1-b.
Start time: The start time of the reservation period, formatted as an RFC 3339 timestamp.
End time: The end time of the reservation period, formatted as an RFC 3339 timestamp. Compute Engine automatically deletes the auto-created reservation, and any VMs that are consuming them, at this time.
Shared projects: If you want to share the requested capacity with other projects in your organization, then you must provide their project numbers. To migrate a project to your organization, see Migrating projects between organization resources in the Resource Manager documentation.
Reservation name: The name of the reservation that Compute Engine automatically creates to deliver the reserved capacity. Compute Engine can only create specifically targeted reservations.

Your TAM works with Google to allocate your requested capacity by creating a future reservation request for you. After the request is created, you can view its details by selecting one of the following options:

gcloud

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

gcloud beta compute future-reservations describe FUTURE_RESERVATION_NAME \
    --zone=ZONE

Replace the following:

FUTURE_RESERVATION_NAME: the name of the future reservation.
ZONE: the zone where the future reservation is located.

The output is similar to the following:

autoCreatedReservationsDeleteTime: '2025-12-17T08:00:00Z'
creationTimestamp: '2022-09-16T10:17:59.903-07:00'
deploymentType: DENSE
id: '6404259976725386921'
kind: compute#futureReservation
name: example-fr1
planningStatus: SUBMITTED
reservationName: example-res1
schedulingType: GROUPED
selfLink: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/futureReservations/example-fr1
selfLinkWithId: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/futureReservations/'6404259976725386921'
specificReservationRequired: true
specificSkuProperties:
  instanceProperties:
    machineType: a3-ultragpu-8g
  totalCount: '100'
status:
  existingMatchingUsageInfo:
    count: '0'
    timestamp: '2024-10-29T12:19:44.132Z'
  lockTime: '2025-09-16T18:00:00Z'
  procurementStatus: APPROVED
timeWindow:
  endTime: '2025-11-25T18:00:00Z'
  startTime: '2025-11-11T18:00:00Z'
zone: https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b

REST

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

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME

Replace the following:

PROJECT_ID: the ID of the project where the future reservation is located.
ZONE: the zone where the future reservation is located.
FUTURE_RESERVATION_NAME: the name of the future reservation.

The output is similar to the following:

{
  "kind": "compute#futureReservation",
  "id": "6404259976725386921",
  "creationTimestamp": "2024-10-17T12:24:55.242-07:00",
  "selfLink": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/futureReservations/example-fr1"
  "selfLinkWithId": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/futureReservations/'6404259976725386921"
  "Zone": "https://compute.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b",
  "name": "exfr1",
  "specificSkuProperties": {
    "instanceProperties": {
      "machineType": "a3-ultragpu-8g"
    },
    "totalCount": "100"
  },
  "timeWindow": {
    "startTime": "2024-09-09T01:00:00Z",
    "endTime": "2025-11-30T08:00:00Z"
  },
  "status": {
    "procurementStatus": "FULFILLED",
    "lockTime": "2024-09-01T00:00:00Z",
    "autoCreatedReservations": [
      "https://compute.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/reservations/example-res1"
    ],
    "fulfilledCount": "100"
  },
  "planningStatus": "SUBMITTED",
  "specificReservationRequired": true,
  "reservationName": "example-res1",
  "deploymentType": "DENSE",
  "schedulingType": "GROUPED",
  "autoCreatedReservationsDeleteTime": "2025-11-30T08:00:00Z"
}

View the delivered capacity

When an approved future reservation enters its start time, Compute Engine automatically creates an on-demand reservation with the capacity that you requested. You can then start consuming the reservation by creating VMs with matching properties.

To review the auto-created reservation, use the following methods:

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

View the details of a reservation

You can view the details of a reservation to review the requested capacity and plan your workload. This 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 an auto-created reservation, select one of the following options:

gcloud

To view the details of an auto-created 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 auto-created reservation is located.

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 an auto-created 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 is located.
ZONE: The zone where the auto-created reservation is located.
RESERVATION_NAME: The name of the auto-created 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 your reserved capacity to help you decide where to create VMs within the reserved blocks. The following fields in the physicalTopology field of a block provides the physical location of the block within a Hypercompute Cluster.

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

To learn more about cluster and block, see Terminology.

To view a list of the available blocks in an auto-created reservation, select one of the following options:

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 auto-create reservation is located.

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: us-central1-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: c18707ac3d2493381c9f01fa775c4a68
  cluster: us-central1-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

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 is located.
ZONE: The zone where the auto-create reservation is located.
RESERVATION_NAME: The name of the auto-created 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": "us-central1-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": "c18707ac3d2493381c9f01fa775c4a68",
        "cluster": "us-central1-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"
    }
  ]
}

What's next

To consume your reserved blocks of resources, do one or more of the following: