Consume a reservation

Note: This page applies to the Cloud TPU API. For Ironwood (TPU7x), you must use Google Kubernetes Engine (GKE). For more information, seeAbout TPUs in GKE.

If you have a TPU reservation, you can use your reserved resources to createTPUs that match the reservation's properties. This action is known asconsuminga reservation. For information about consuming a TPU reservation when usingGoogle Kubernetes Engine (GKE), seeTPUreservation in theGKE documentation.

Important: When you consume a future reservation that was created in calendarmode, you must specify the name of the reservation you want toconsume, described in the next section.

Consume a specific reservation

When you create resources with thegcloud alpha compute tpus queued-resourcescreatecommand, usethe--reservationflagto specify the name of the reservation to consume. For future reservationscreated in calendar mode, you must also set the--provisioning-modelflagtoreservation-bound:

gcloudalphacomputetpusqueued-resourcescreateQUEUED_RESOURCE_ID\--node-id=TPU_NAME\--zone=ZONE\--accelerator-type=ACCELERATOR_TYPE\--runtime-version=SOFTWARE_VERSION\--reservation=RESERVATION_URL\--provisioning-model=reservation-bound# Only required for calendar mode

Replace the following placeholder variables:

  • QUEUED_RESOURCE_ID: A user-assigned ID for the queued resource request.
  • TPU_NAME: A user-assigned ID (name) for the TPU that is created when the queuedresource request is allocated.
  • ZONE: The zone in which to create the TPU VM. For more informationabout supported zones, seeRegions and zones.
  • ACCELERATOR_TYPE: Specifies the version and size of the Cloud TPU tocreate. For more information about supported accelerator types for each TPUversion, seeTPU versions.
  • SOFTWARE_VERSION: The Cloud TPUsoftware version.
  • RESERVATION_URL: The URL of the reservation. Specify one of thefollowing values:
    • If the reservation is in your project:RESERVATION_NAME
    • If the reservation is in another project and your project can consumeit:projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME

Consume any matching reservation

Important: This method is not supported for future reservations created incalendar mode. When you consume a future reservation created in calendar mode,you must specify the name of the reservation you want to consume, described inthe previous section.

You can use the--reserved flag to automatically determine the reservation touse based on the accelerator type, project ID, and zone.

CreateNode

To consume any matching reservation using the CreateNode API, use thegcloudalpha compute tpus tpu-vm createcommand with the--reservedflag:

gcloudalphacomputetpustpu-vmcreateTPU_NAME\--zone=ZONE\--accelerator-type=ACCELERATOR_TYPE\--version=SOFTWARE_VERSION\--reserved

Replace the following placeholder variables:

  • TPU_NAME: A name for the TPU.
  • ZONE: The zone where to create the TPU VM, which must match thereservation zone.
  • ACCELERATOR_TYPE: Specifies the version and size of the Cloud TPU tocreate. For more information about supported accelerator types for each TPUversion, seeTPU versions.
  • SOFTWARE_VERSION: The Cloud TPUsoftware version.

Queued resources

To consume any matching reservation usingqueuedresources, use thegcloud alpha compute tpusqueued-resources createcommand withthe--reservedflag:

gcloudalphacomputetpusqueued-resourcescreateQUEUED_RESOURCE_ID\--node-id=TPU_NAME\--zone=ZONE\--accelerator-type=ACCELERATOR_TYPE\--runtime-version=SOFTWARE_VERSION\--reserved

Replace the following placeholder variables:

  • QUEUED_RESOURCE_ID: A user-assigned ID for the queued resource request.
  • TPU_NAME: A user-assigned ID (name) for the TPU that is created when the queuedresource request is allocated.
  • ZONE: The zone in which to create the TPU VM and where thereservation exists.
  • ACCELERATOR_TYPE: Specifies the version and size of the Cloud TPU tocreate. For more information about supported accelerator types for each TPUversion, seeTPU versions.
  • SOFTWARE_VERSION: The Cloud TPUsoftware version.

Check reservation usage

You can only check a shared reservation usage from its owner project. If you arein a consumer project, then you must switch to the owner project to check thereservation usage.

To see how much of the reservation is in use, use thegcloud computereservations describecommand:

gcloudcomputereservationsdescribeRESERVATION_NAME\--project=PROJECT_ID--zone=ZONE

Replace the following placeholder variables:

  • RESERVATION_NAME: The name of the reservation.
  • PROJECT_ID: The ID of the project that contains the reservation.
  • ZONE: The zone where the reservation exists.

To list all reservations in a project, use thegcloud compute reservationslist command:

gcloudcomputereservationslist--project=PROJECT_ID

Replace the following placeholder variable:

  • PROJECT_ID: The ID of the project.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.