Manage queued resources

Queued resources enable you to request Cloud TPU resources in a queued manner. When you create a queued resource request, the request is added to a queue maintained by the Cloud TPU service. When the resource you requested becomes available, it's assigned to your Google Cloud project for your immediate and exclusive use. It will remain assigned to your project unless you delete it or it's preempted. Only TPU Spot VMs and preemptible TPUs are eligible for preemption.

You can specify an optional start and end time in a queued resource request. The start time specifies the earliest time in which to fill the request. If a request has not been filled by the specified end time, the request expires. The request remains in the queue after it has expired.

Queued resource requests can be in one the following states:

WAITING_FOR_RESOURCES: The request has passed initial validation and has been added to the queue. It remains in this state until there are sufficient free resources to begin provisioning your request or the allocation interval elapses. When demand is high, not all requests can be immediately provisioned. If you need more reliable obtainability of TPUs, consider purchasing a reservation.
Important: WAITING_FOR_RESOURCES replaced the ACCEPTED state. If your code has logic that waits for queued resources to enter the ACCEPTED state, you may need to update the code to wait for the WAITING_FOR_RESOURCES state.
PROVISIONING: The request has been selected from the queue and its resources are being allocated.
ACTIVE: The request has been allocated. When queued resource requests are in the ACTIVE state, you can manage your TPU VMs as described in Manage TPUs.
FAILED: The request couldn't be completed, either because there is a problem with the request or the requested resources were not available within the allocation interval. The request remains in the queue until it is explicitly deleted.
SUSPENDING: The resources associated with the request are being deleted.
SUSPENDED: The resources specified in the request have been deleted. When a request is in the SUSPENDED state, it's no longer eligible for further allocation.

Prerequisites

Before you run the commands in this guide, you must install the Google Cloud CLI, create a Google Cloud project, and enable the Cloud TPU API. For instructions, see Set up the Cloud TPU environment.

If you're using one of the Cloud Client Libraries, follow the setup instructions for the language you're using:

Python
Java

Request an on-demand queued resource

On-demand resources won't be preempted, but on-demand quota doesn't guarantee there will be enough available Cloud TPU resources to satisfy your request. For more information about on-demand resources, see Quota types.

gcloud

gcloud compute tpus queued-resources create your-queued-resource-id \
    --node-id your-node-id \
    --project your-project-id \
    --zone us-central1-a \
    --accelerator-type v5litepod-8 \
    --runtime-version v2-alpha-tpuv5-lite

Command parameter descriptions

queued-resource-id: The user-assigned ID of the queued resource request.
node-id: The user-assigned ID of the TPU which is created when the queued resource request is allocated.
project: Your Google Cloud project.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-central1-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5litepod-8',
        'runtime_version': 'v2-alpha-tpuv5-lite',
        }
    }
    }
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-central1-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-id: The user-assigned ID of the queued resource request.
node-id: The user-assigned ID of the TPU which is created when the queued resource request is allocated.
project: Your Google Cloud project.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.

Console

In the Google Cloud console, go to the TPUs page:

Go to TPUs
Click Create TPU.
In the Name field, enter a name for your TPU.
In the Zone box, select the zone where you want to create the TPU.
In the TPU type box, select an accelerator type. The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
In the TPU software version box, select a software version. When creating a Cloud TPU VM, the TPU software version specifies the version of the TPU runtime to install. For more information, see TPU software versions.
Click the Enable queueing toggle.
In the Queued resource name field, enter a name for your queued resource request.
Click Create to create your queued resource request.

Java

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.tpu.v2alpha1.CreateQueuedResourceRequest;
import com.google.cloud.tpu.v2alpha1.Node;
import com.google.cloud.tpu.v2alpha1.QueuedResource;
import com.google.cloud.tpu.v2alpha1.TpuClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateQueuedResource {
  public static void main(String[] args)
          throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Google Cloud project you want to create a node.
    String projectId = "YOUR_PROJECT_ID";
    // The zone in which to create the TPU.
    // For more information about supported TPU types for specific zones,
    // see https://cloud.google.com/tpu/docs/regions-zones
    String zone = "us-central1-a";
    // The name for your TPU.
    String nodeName = "YOUR_NODE_ID";
    // The accelerator type that specifies the version and size of the Cloud TPU you want to create.
    // For more information about supported accelerator types for each TPU version,
    // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions.
    String tpuType = "v5litepod-4";
    // Software version that specifies the version of the TPU runtime to install.
    // For more information see https://cloud.google.com/tpu/docs/runtimes
    String tpuSoftwareVersion = "v2-tpuv5-litepod";
    // The name for your Queued Resource.
    String queuedResourceId = "QUEUED_RESOURCE_ID";

    createQueuedResource(
        projectId, zone, queuedResourceId, nodeName, tpuType, tpuSoftwareVersion);
  }

  // Creates a Queued Resource
  public static QueuedResource createQueuedResource(String projectId, String zone,
      String queuedResourceId, String nodeName, String tpuType, String tpuSoftwareVersion)
          throws IOException, ExecutionException, InterruptedException, TimeoutException {
    String resource = String.format("projects/%s/locations/%s/queuedResources/%s",
            projectId, zone, queuedResourceId);
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (TpuClient tpuClient = TpuClient.create()) {
      String parent = String.format("projects/%s/locations/%s", projectId, zone);
      Node node =
          Node.newBuilder()
              .setName(nodeName)
              .setAcceleratorType(tpuType)
              .setRuntimeVersion(tpuSoftwareVersion)
              .setQueuedResource(resource)
              .build();

      QueuedResource queuedResource =
          QueuedResource.newBuilder()
              .setName(queuedResourceId)
              .setTpu(
                  QueuedResource.Tpu.newBuilder()
                      .addNodeSpec(
                          QueuedResource.Tpu.NodeSpec.newBuilder()
                              .setParent(parent)
                              .setNode(node)
                              .setNodeId(nodeName)
                              .build())
                      .build())
              .build();

      CreateQueuedResourceRequest request =
          CreateQueuedResourceRequest.newBuilder()
              .setParent(parent)
              .setQueuedResourceId(queuedResourceId)
              .setQueuedResource(queuedResource)
              .build();

      return tpuClient.createQueuedResourceAsync(request).get(1, TimeUnit.MINUTES);
    }
  }
}

Python

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import tpu_v2alpha1

# TODO(developer): Update and un-comment below lines
# project_id = "your-project-id"
# zone = "us-central1-a"
# tpu_name = "tpu-name"
# tpu_type = "v5litepod-4"
# runtime_version = "v2-tpuv5-litepod"
# queued_resource_name = "resource-name"

node = tpu_v2alpha1.Node()
node.accelerator_type = tpu_type
# To see available runtime version use command:
# gcloud compute tpus versions list --zone={ZONE}
node.runtime_version = runtime_version

node_spec = tpu_v2alpha1.QueuedResource.Tpu.NodeSpec()
node_spec.parent = f"projects/{project_id}/locations/{zone}"
node_spec.node_id = tpu_name
node_spec.node = node

resource = tpu_v2alpha1.QueuedResource()
resource.tpu = tpu_v2alpha1.QueuedResource.Tpu(node_spec=[node_spec])

request = tpu_v2alpha1.CreateQueuedResourceRequest(
    parent=f"projects/{project_id}/locations/{zone}",
    queued_resource_id=queued_resource_name,
    queued_resource=resource,
)

client = tpu_v2alpha1.TpuClient()
operation = client.create_queued_resource(request=request)

response = operation.result()
print(response.name)
print(response.state)
# Example response:
# projects/[project_id]/locations/[zone]/queuedResources/resource-name
# State.WAITING_FOR_RESOURCES

Request a queued resource using a reservation

You can request a queued resource using a reservation. To purchase a reservation, contact your Google Cloud account team.

gcloud

gcloud compute tpus queued-resources create your-queued-resource-id \
    --node-id your-node-id \
    --project your-project-id \
    --zone us-central1-a \
    --accelerator-type v5litepod-8 \
    --runtime-version v2-alpha-tpuv5-lite \
    --reserved

Command parameter descriptions

queued-resource-id: The user-assigned ID of the queued resource request.
node-id: The user-assigned ID of the TPU which is created when the queued resource request is allocated.
project: Your Google Cloud project.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
reserved: Use this flag when requesting queued resources as part of a Cloud TPU reservation.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-central1-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5litepod-8',
        'runtime_version': 'v2-alpha-tpuv5-lite',
        }
    }
    },
    'guaranteed': {
    'reserved': true,
    }
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-central1-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-id: The user-assigned ID of the queued resource request.
node-id: The user-assigned ID of the TPU which is created when the queued resource request is allocated.
project: Your Google Cloud project.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
reserved: Use this flag when requesting queued resources as part of a Cloud TPU reservation.

Console

In the Google Cloud console, go to the TPUs page:

Go to TPUs
Click Create TPU.
In the Name field, enter a name for your TPU.
In the Zone box, select the zone where you want to create the TPU.
In the TPU type box, select an accelerator type. The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
In the TPU software version box, select a software version. When creating a Cloud TPU VM, the TPU software version specifies the version of the TPU runtime to install. For more information, see TPU software versions.
Click the Enable queueing toggle.
In the Queued resource name field, enter a name for your queued resource request.
Expand the Management section.
Select the Use existing reservation checkbox.
Click Create to create your queued resource request.

Request a TPU Spot VM queued resource

A Spot VM is a resource that can be preempted and assigned to another workload at any time. Spot VM resources cost less, and you might get access to resources sooner compared to a non-Spot VM request. For more information about TPU Spot VMs, see Manage TPU Spot VMs.

gcloud

gcloud compute tpus queued-resources create your-queued-resource-id \
    --node-id your-node-id \
    --project your-project-id \
    --zone us-central1-a \
    --accelerator-type v5litepod-8 \
    --runtime-version v2-alpha-tpuv5-lite \
    --spot

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The ID of the project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
spot: A boolean flag specifying that the queued resource is a Spot VM.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-central1-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5litepod-8',
        'runtime_version': 'v2-alpha-tpuv5-lite'
        }
    }
    },
    'spot': {}
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-central1-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The ID of the project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
spot: A boolean flag specifying that the queued resource is a Spot VM.

Console

In the Google Cloud console, go to the TPUs page:

Go to TPUs
Click Create TPU.
In the Name field, enter a name for your TPU.
In the Zone box, select the zone where you want to create the TPU.
In the TPU type box, select an accelerator type. The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
In the TPU software version box, select a software version. When creating a Cloud TPU VM, the TPU software version specifies the version of the TPU runtime to install. For more information, see TPU software versions.
Click the Enable queueing toggle.
In the Queued resource name field, enter a name for your queued resource request.
Expand the Management section.
Select the Make this a TPU Spot VM checkbox.
Click Create.

Java

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.tpu.v2alpha1.CreateQueuedResourceRequest;
import com.google.cloud.tpu.v2alpha1.Node;
import com.google.cloud.tpu.v2alpha1.QueuedResource;
import com.google.cloud.tpu.v2alpha1.SchedulingConfig;
import com.google.cloud.tpu.v2alpha1.TpuClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class CreateSpotQueuedResource {
  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Google Cloud project you want to create a node.
    String projectId = "YOUR_PROJECT_ID";
    // The zone in which to create the TPU.
    // For more information about supported TPU types for specific zones,
    // see https://cloud.google.com/tpu/docs/regions-zones
    String zone = "us-central1-a";
    // The name for your TPU.
    String nodeName = "YOUR_TPU_NAME";
    // The accelerator type that specifies the version and size of the Cloud TPU you want to create.
    // For more information about supported accelerator types for each TPU version,
    // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions.
    String tpuType = "v5litepod-4";
    // Software version that specifies the version of the TPU runtime to install.
    // For more information see https://cloud.google.com/tpu/docs/runtimes
    String tpuSoftwareVersion = "v2-tpuv5-litepod";
    // The name for your Queued Resource.
    String queuedResourceId = "QUEUED_RESOURCE_ID";

    createQueuedResource(
        projectId, zone, queuedResourceId, nodeName, tpuType, tpuSoftwareVersion);
  }

  // Creates a Queued Resource with --preemptible flag.
  public static QueuedResource createQueuedResource(
      String projectId, String zone, String queuedResourceId,
      String nodeName, String tpuType, String tpuSoftwareVersion)
      throws IOException, ExecutionException, InterruptedException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (TpuClient tpuClient = TpuClient.create()) {
      String parent = String.format("projects/%s/locations/%s", projectId, zone);
      String resourceName = String.format("projects/%s/locations/%s/queuedResources/%s",
              projectId, zone, queuedResourceId);
      SchedulingConfig schedulingConfig = SchedulingConfig.newBuilder()
          .setPreemptible(true)
          .build();

      Node node =
          Node.newBuilder()
              .setName(nodeName)
              .setAcceleratorType(tpuType)
              .setRuntimeVersion(tpuSoftwareVersion)
              .setSchedulingConfig(schedulingConfig)
              .setQueuedResource(resourceName)
              .build();

      QueuedResource queuedResource =
          QueuedResource.newBuilder()
              .setName(queuedResourceId)
              .setTpu(
                  QueuedResource.Tpu.newBuilder()
                      .addNodeSpec(
                          QueuedResource.Tpu.NodeSpec.newBuilder()
                              .setParent(parent)
                              .setNode(node)
                              .setNodeId(nodeName)
                              .build())
                      .build())
              .build();

      CreateQueuedResourceRequest request =
          CreateQueuedResourceRequest.newBuilder()
              .setParent(parent)
              .setQueuedResourceId(queuedResourceId)
              .setQueuedResource(queuedResource)
              .build();

      return tpuClient.createQueuedResourceAsync(request).get();
    }
  }
}

Python

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import tpu_v2alpha1

# TODO(developer): Update and un-comment below lines
# project_id = "your-project-id"
# zone = "us-central1-a"
# tpu_name = "tpu-name"
# tpu_type = "v5litepod-4"
# runtime_version = "v2-tpuv5-litepod"
# queued_resource_name = "resource-name"

node = tpu_v2alpha1.Node()
node.accelerator_type = tpu_type
# To see available runtime version use command:
# gcloud compute tpus versions list --zone={ZONE}
node.runtime_version = runtime_version

node_spec = tpu_v2alpha1.QueuedResource.Tpu.NodeSpec()
node_spec.parent = f"projects/{project_id}/locations/{zone}"
node_spec.node_id = tpu_name
node_spec.node = node

resource = tpu_v2alpha1.QueuedResource()
resource.tpu = tpu_v2alpha1.QueuedResource.Tpu(node_spec=[node_spec])
# Create a spot resource
resource.spot = tpu_v2alpha1.QueuedResource.Spot()

request = tpu_v2alpha1.CreateQueuedResourceRequest(
    parent=f"projects/{project_id}/locations/{zone}",
    queued_resource_id=queued_resource_name,
    queued_resource=resource,
)

client = tpu_v2alpha1.TpuClient()
operation = client.create_queued_resource(request=request)
response = operation.result()

print(response.name)
print(response.state)
# Example response:
# projects/[project_id]/locations/[zone]/queuedResources/resource-name
# State.WAITING_FOR_RESOURCES

Request a queued resource to be allocated before or after a specified time

You can specify an optional start time or end time in a queued resource request. The start time or start duration specifies the earliest time in which to fill the request. The end time or end duration specifies how long the request remains valid. If a request hasn't been filled by the specified end time or within the specified duration, the request expires. After the request has expired, it remains in the queue but is no longer eligible for allocation.

You can also specify an allocation interval by specifying a start time or duration and an end time or duration.

For a list of supported timestamp and duration formats, see Datetime.

Request a queued resource to be fulfilled after a specified time

In a queued resource request, you can specify a time or duration after which a resource should be allocated.

gcloud

The following command requests a v5p-4096 TPU with to be allocated after 9AM on December 14, 2022.

gcloud compute tpus queued-resources create your-queued-resource-id \
    --node-id your-node-id \
    --project your-project-id \
    --zone us-east5-a \
    --accelerator-type v5p-4096 \
    --runtime-version v2-alpha-tpuv5 \
    --valid-after-time 2022-12-14T09:00:00Z

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The Google Cloud project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
valid-after-time: The time, after which, the resource should be allocated For more information on duration formats, see Google Cloud CLI topic datetime.

curl

The following command requests a v5p-4096 TPU with to be allocated after 9AM on December 14, 2022.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-east5-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5p-4096',
        'runtime_version': 'v2-alpha-tpuv5',
        }
    }
    },
    'queueing_policy': {
    'valid_after_time': {
        'seconds': 2022-12-14T09:00:00Z
    }
    }
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-east5-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The Google Cloud project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
valid-after-time: The time, after which, the resource should be allocated For more information on duration formats, see Google Cloud CLI topic datetime.

Console

In the Google Cloud console, go to the TPUs page:

Go to TPUs
Click Create TPU.
In the Name field, enter a name for your TPU.
In the Zone box, select the zone where you want to create the TPU.
In the TPU type box, select an accelerator type. The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
In the TPU software version box, select a software version. When creating a Cloud TPU VM, the TPU software version specifies the version of the TPU runtime to install. For more information, see [TPU version of the TPU runtime to install. For more information, see TPU software versions.
Click the Enable queueing toggle.
In the Queued resource name field, enter a name for your queued resource request.
In the Start request on field, enter the time after which the resource should be allocated.
Click Create to create your queued resource request.

The following example requests a v5p-32 to be allocated after six hours.

gcloud

    gcloud compute tpus queued-resources create your-queued-resource-id \
        --node-id your-node-id \
        --project your-project-id \
        --zone us-east5-a \
        --accelerator-type v5p-32 \
        --runtime-version v2-alpha-tpuv5 \
        --valid-after-duration 6h

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The Google Cloud project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
valid-after-duration: The duration before which the TPU must not be provisioned. For more information on duration formats, see Google Cloud CLI topic datetime

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-east5-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5p-32',
        'runtime_version': 'v2-alpha-tpuv5',
        }
    }
    },
'queueing_policy': {
    'valid_after_duration': {
        'seconds': 21600
    }
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-east5-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The Google Cloud project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
valid-after-duration: The duration before which the TPU must not be provisioned. For more information on duration formats, see Google Cloud CLI topic datetime

Java

To authenticate to Cloud TPU, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.tpu.v2alpha1.CreateQueuedResourceRequest;
import com.google.cloud.tpu.v2alpha1.Node;
import com.google.cloud.tpu.v2alpha1.QueuedResource;
import com.google.cloud.tpu.v2alpha1.TpuClient;
import com.google.protobuf.Duration;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class CreateTimeBoundQueuedResource {

  public static void main(String[] args)
          throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Google Cloud project you want to create a node.
    String projectId = "YOUR_PROJECT_ID";
    // The zone in which to create the TPU.
    // For more information about supported TPU types for specific zones,
    // see https://cloud.google.com/tpu/docs/regions-zones
    String zone = "us-central2-b";
    // The name of your node.
    String nodeId = "YOUR_NODE_ID";
    // The accelerator type that specifies the version and size of the Cloud TPU you want to create.
    // For more information about supported accelerator types for each TPU version,
    // see https://cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions.
    String acceleratorType = "v2-8";
    // Software version that specifies the version of the TPU runtime to install.
    // For more information see https://cloud.google.com/tpu/docs/runtimes
    String runtimeVersion = "v2-tpuv5-litepod";
    // The name of your Queued Resource.
    String queuedResourceId = "YOUR_QUEUED_RESOURCE_ID";

    createTimeBoundQueuedResource(projectId, nodeId,
        queuedResourceId, zone, acceleratorType, runtimeVersion);
  }

  // Creates a Queued Resource with time bound configuration.
  public static QueuedResource createTimeBoundQueuedResource(
      String projectId, String nodeId, String queuedResourceId,
      String zone, String acceleratorType, String runtimeVersion)
          throws IOException, ExecutionException, InterruptedException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (TpuClient tpuClient = TpuClient.create()) {
      String parent = String.format("projects/%s/locations/%s", projectId, zone);
      // Create a Duration object representing 6 hours.
      Duration validAfterDuration = Duration.newBuilder().setSeconds(6 * 3600).build();
      // You could also use timestamps like this:
      // Timestamp validAfterTime = Timestamps.parse("2024-10-14T09:00:00Z");

      Node node =
          Node.newBuilder()
              .setName(nodeId)
              .setAcceleratorType(acceleratorType)
              .setRuntimeVersion(runtimeVersion)
              .setQueuedResource(
                  String.format(
                      "projects/%s/locations/%s/queuedResources/%s",
                      projectId, zone, queuedResourceId))
              .build();

      QueuedResource queuedResource =
          QueuedResource.newBuilder()
              .setName(queuedResourceId)
              .setTpu(
                  QueuedResource.Tpu.newBuilder()
                      .addNodeSpec(
                          QueuedResource.Tpu.NodeSpec.newBuilder()
                              .setParent(parent)
                              .setNode(node)
                              .setNodeId(nodeId)
                              .build())
                      .build())
              .setQueueingPolicy(
                  QueuedResource.QueueingPolicy.newBuilder()
                      .setValidAfterDuration(validAfterDuration)
                      // .setValidAfterTime(validAfterTime)
                      .build())
              .build();

      CreateQueuedResourceRequest request =
          CreateQueuedResourceRequest.newBuilder()
              .setParent(parent)
              .setQueuedResource(queuedResource)
              .setQueuedResourceId(queuedResourceId)
              .build();

      return tpuClient.createQueuedResourceAsync(request).get();
    }
  }
}

Request a queued resource that expires after a specified time

In a queued resource request, you can specify how long a queued resource request remains valid. If the request hasn't been fulfilled by the time or duration you specify, the request expires.

gcloud

The following command requests a v5p-4096 TPU. If the request isn't fulfilled by December 14, 2022 at 9:00 AM, the request expires.

gcloud compute tpus queued-resources create your-queued-resource-id \
    --node-id your-node-id \
    --project your-project-id \
    --zone us-east5-a \
    --accelerator-type v5p-4096 \
    --runtime-version v2-alpha-tpuv5 \
    --valid-until-time 2022-12-14T09:00:00Z

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The ID of the project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.
valid-until-time: The time after which the request is canceled. For more information on duration formats, see Google Cloud CLI topic datetime.

curl

The following command requests a v5p-4096 TPU. If the request isn't fulfilled by December 14, 2022 at 9:00 AM, the request expires.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d "{
    'tpu': {
    'node_spec': {
        'parent': 'projects/your-project-number/locations/us-east5-a',
        'node_id': 'your-node-id',
        'node': {
        'accelerator_type': 'v5p-4096',
        'runtime_version': 'v2-alpha-tpuv5',
        }
    }
    },
    'queueing_policy': {
    'valid_until_time': {
        'seconds': 1655197200
    }
    }
}" \
https://tpu.googleapis.com/v2alpha1/projects/your-project-id/locations/us-east5-a/queuedResources?queued_resource_id=your-queued-resource-id

Command parameter descriptions

queued-resource-request-id: The user-assigned ID of the queued resource request.
node-id: The user-defined ID of the TPU created in response to the request.
project: The ID of the project where the queued resource is allocated.
zone: The zone where you plan to create your Cloud TPU.
accelerator-type: The accelerator type specifies the version and size of the Cloud TPU you want to create. For more information about supported accelerator types for each TPU version, see TPU versions.
runtime-version: The Cloud TPU software version.