# Consume a reservation

> [!CAUTION]
> **Caution:** This page applies to the Cloud TPU API, which is no longer under active development. The Cloud TPU API will receive bug fixes and security updates only. For the latest features and support for the latest TPU versions, we recommend using Compute Engine or Google Kubernetes Engine to manage TPU resources. For more information, see [TPU resources in Compute Engine](https://docs.cloud.google.com/tpu/docs/tpus-in-compute-engine.md.txt) and [About TPUs in GKE](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/tpus.md.txt). The Cloud TPU API is not supported on TPU7x and later TPU versions.

If you have a TPU reservation, you can use your reserved resources to create
TPUs that match the reservation's properties. This action is known as *consuming
a reservation* . For information about consuming a TPU reservation when using
Google Kubernetes Engine (GKE), see [TPU
reservation](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/plan-tpus#tpu_reservation) in the
GKE documentation.

> [!IMPORTANT]
> **Important:** When you consume a future reservation that was created in calendar mode, you must specify the name of the reservation you want to consume, described in the next section.

## Consume a specific reservation

When you create resources with the [`gcloud alpha compute tpus queued-resources
create`
command](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/queued-resources/create), use
the [`--reservation`
flag](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/queued-resources/create#--reservation)
to specify the name of the reservation to consume. For future reservations
created in calendar mode, you must also set the [`--provisioning-model`
flag](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/queued-resources/create#--provisioning-model)
to `reservation-bound`:

```bash
gcloud alpha compute tpus queued-resources create QUEUED_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:

- <var translate="no">QUEUED_RESOURCE_ID</var>: A user-assigned ID for the queued resource request.
- <var translate="no">TPU_NAME</var>: A user-assigned ID (name) for the TPU that is created when the queued resource request is allocated.
- <var translate="no">ZONE</var>: The zone in which to create the TPU VM. For more information about supported zones, see [Regions and zones](https://docs.cloud.google.com/tpu/docs/regions-zones.md.txt).
- <var translate="no">ACCELERATOR_TYPE</var>: Specifies the version and size of the Cloud TPU to create. For more information about supported accelerator types for each TPU version, see [TPU versions](https://docs.cloud.google.com/tpu/docs/system-architecture-tpu-vm.md.txt#versions).
- <var translate="no">SOFTWARE_VERSION</var>: The Cloud TPU [software version](https://docs.cloud.google.com/tpu/docs/runtimes.md.txt).
- <var translate="no">RESERVATION_URL</var>: The URL of the reservation. Specify one of the following values:
  - If the reservation is in your project: `RESERVATION_NAME`
  - If the reservation is in another project and your project can consume it: `projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME`

## Consume any matching reservation

> [!IMPORTANT]
> **Important:** This method is not supported for future reservations created in calendar mode. When you consume a future reservation created in calendar mode, you must specify the name of the reservation you want to consume, described in the previous section.

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

### CreateNode

To consume any matching reservation using the CreateNode API, use the [`gcloud
alpha compute tpus tpu-vm create`
command](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/tpu-vm/create) with the
[`--reserved`
flag](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/tpu-vm/create#--reserved):

```bash
gcloud alpha compute tpus tpu-vm create TPU_NAME \
    --zone=ZONE \
    --accelerator-type=ACCELERATOR_TYPE \
    --version=SOFTWARE_VERSION \
    --reserved
```

Replace the following placeholder variables:

- <var translate="no">TPU_NAME</var>: A name for the TPU.
- <var translate="no">ZONE</var>: The zone where to create the TPU VM, which must match the reservation zone.
- <var translate="no">ACCELERATOR_TYPE</var>: Specifies the version and size of the Cloud TPU to create. For more information about supported accelerator types for each TPU version, see [TPU versions](https://docs.cloud.google.com/tpu/docs/system-architecture-tpu-vm.md.txt#versions).
- <var translate="no">SOFTWARE_VERSION</var>: The Cloud TPU [software version](https://docs.cloud.google.com/tpu/docs/runtimes.md.txt).

### Queued resources

To consume any matching reservation using [queued
resources](https://docs.cloud.google.com/tpu/docs/queued-resources), use the [`gcloud alpha compute tpus
queued-resources create`
command](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/queued-resources/create) with
the [`--reserved`
flag](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/compute/tpus/queued-resources/create#--reserved):

```bash
gcloud alpha compute tpus queued-resources create QUEUED_RESOURCE_ID \
    --node-id=TPU_NAME \
    --zone=ZONE \
    --accelerator-type=ACCELERATOR_TYPE \
    --runtime-version=SOFTWARE_VERSION \
    --reserved
```

Replace the following placeholder variables:

- <var translate="no">QUEUED_RESOURCE_ID</var>: A user-assigned ID for the queued resource request.
- <var translate="no">TPU_NAME</var>: A user-assigned ID (name) for the TPU that is created when the queued resource request is allocated.
- <var translate="no">ZONE</var>: The zone in which to create the TPU VM and where the reservation exists.
- <var translate="no">ACCELERATOR_TYPE</var>: Specifies the version and size of the Cloud TPU to create. For more information about supported accelerator types for each TPU version, see [TPU versions](https://docs.cloud.google.com/tpu/docs/system-architecture-tpu-vm.md.txt#versions).
- <var translate="no">SOFTWARE_VERSION</var>: The Cloud TPU [software version](https://docs.cloud.google.com/tpu/docs/runtimes.md.txt).

## Check reservation usage

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

To see how much of the reservation is in use, use the [`gcloud compute
reservations describe`
command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/reservations/describe):

```bash
gcloud compute reservations describe RESERVATION_NAME \
    --project=PROJECT_ID --zone=ZONE
```

Replace the following placeholder variables:

- <var translate="no">RESERVATION_NAME</var>: The name of the reservation.
- <var translate="no">PROJECT_ID</var>: The ID of the project that contains the reservation.
- <var translate="no">ZONE</var>: The zone where the reservation exists.

To list all reservations in a project, use the [`gcloud compute reservations
list` command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/reservations/list):

```bash
gcloud compute reservations list --project=PROJECT_ID
```

Replace the following placeholder variable:

- <var translate="no">PROJECT_ID</var>: The ID of the project.

## What's next

- [Learn about Cloud TPU reservations](https://docs.cloud.google.com/tpu/docs/about-tpu-reservations.md.txt)
- [Share a reservation between projects](https://docs.cloud.google.com/tpu/docs/share-reservation.md.txt)
- [Manage your TPUs](https://docs.cloud.google.com/tpu/docs/managing-tpus-tpu-vm.md.txt)