Request capacity

This document explains how to reserve blocks of capacity using future reservation requests. To learn more about future reservation requests, including their pricing 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:

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 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 or A4 machine type.

  • 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:

  1. Request capacity for multiple blocks. Contact your assigned TAM to request capacity. This action involves specifying the type and amount of resources that you need.

  2. Review and submit the draft reservation requests. After you request capacity, review your reservation request. If it looks correct, then submit the request for review. Google Cloud immediately approves your request.

  3. View the delivered capacity. After your reservation request enters its start time, you can view the delivered capacity. This action 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 project 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 or A4 machine that you want to reserve. You can only reserve multiples of 2 VMs.

  • Zone: The zone where you want to reserve the capacity. For a list of available A3 Ultra and A4 regions and zones, see GPU regions and zones.

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

  • Share type: Whether you want a single project or multiple projects to consume the reserved capacity. To share the reserved capacity with multiple projects in your organization, do the following:

    • In the project in which the future reservation is created, ensure that you've enabled shared reservations creation.

    • Provide the project numbers of the projects that you want to share the reserved capacity with.

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

  • Optional: Commitment name: If your reservation is one year or more, then you can provide a name for a Resource-based commitment. Compute Engine can automatically create this commitment for your machines along with the reservation. These resource-based commitments are available for either one year or three years.

Review and submit the draft reservation requests

Your TAM works with Google to allocate your requested capacity by creating a draft future reservation request for you by using the information that you provided in the preceding section.

When the draft future reservation request is ready, your TAM contacts you to submit the reservation request.

To submit a draft future reservation request to Google Cloud for review, select one of the following options:

Console

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

    Go to Reservations

  2. Click the Future reservations tab. The table lists each reservation request.

  3. Look for the reservation request that has the name you provided and is in Drafting state.

  4. To view the details of the draft request, in the Name column, click the name of the request. A page that provides a detailed view of the future reservation request opens.

  5. In the Basic information section, check that the details such as start date, end date, and share type are correct. Also, if you requested a commitment, ensure that this commitment is specified.

  6. If everything looks accurate, Click Submit. Otherwise, contact your TAM.

When you submit the request, Google Cloud automatically approves it.

gcloud

  1. View the future reservations that are available by using the gcloud beta compute future-reservations list command:

    gcloud beta compute future-reservations list

  2. From the list, look for the reservation request that has the name that you provided and the status PROCUREMENT_STATUS: DRAFTING.

  3. View the details of the draft future reservation request by using the gcloud beta compute future-reservations describe command:

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

  4. Check that the details such as start date, end date, and share type are correct. Also, if you requested a commitment, ensure that this commitment is specified.

  5. Submit the draft future reservation request for review by using the gcloud beta compute future-reservations update command with the --planning-status flag set to SUBMITTED.

    gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
    --planning-status=SUBMITTED \
    --zone=ZONE

    Replace the following:

    • FUTURE_RESERVATION_NAME: the name of the draft future reservation request.

    • ZONE: the zone where the future reservation request is to be created.

    When you submit the request, Google Cloud automatically approves it.

REST

  1. View the future reservations that are available by making a GET request to the beta.futureReservations.list method:

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

  2. From the list, look for the reservation request that has the name that you provided and the status "planningStatus": "DRAFT".

  3. View the details of the draft future reservation request by making 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

  4. To submit a draft future reservation request for review, make a PATCH request to the beta.futureReservations.update method. In the request body, include the planningStatus field and set it to SUBMITTED.

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=planningStatus

{
  "name": "FUTURE_RESERVATION_NAME",
  "planningStatus": "SUBMITTED"
}

    Replace the following:

    • PROJECT_ID: the ID of the project where the future reservation request is to be located.

    • ZONE: the zone where the future reservation request is to be created.

    • FUTURE_RESERVATION_NAME: the name of the draft future reservation request.

When you submit the request, Google Cloud automatically approves it.

View the delivered capacity

After Google Cloud approves a reservation request, Compute Engine automatically creates (auto-create) a reservation with the capacity that you requested at the start time specified in your future reservation. You can then start consuming the reservation by creating your A4 or A3 Ultra VMs.

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

View the details of a reservation

You can view the details of a 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

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

    Go to Reservations

  2. 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 for the reservation opens.

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

  • 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 a reservation topology

You can view the detailed topology information of your reserved capacity to help you decide where to create VMs within the reserved blocks.

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

Console

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

    Go to Reservations

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

  3. 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 a 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 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 reserved block, you can see 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.

REST

To view a list of the available blocks in a 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 Compute Engine automatically created the reservation.

  • 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 reserved block, you can see 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.

What's next

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