Create a Cloud TPU VM instance using Compute Engine

This document shows you how to create a single TPU VM with the Compute Engine gcloud compute instances create command. You can also create a TPU VM instance by specifying an instance template. For more information, see Create a VM from an instance template.

Prerequisites

Complete the following prerequisites:

1. Create a Google Cloud project for your TPUs as described in Set up a Google Cloud project for TPUs.

2. Determine your TPU requirements as described in Plan your Cloud TPU resources.

Create a TPU VM instance

The parameters you use to create a TPU VM instance depend on the consumption option you are using: on-demand, Spot, reservation-bound, or flex-start. For more information, see Plan your TPU resources .

Create an on-demand TPU VM instance

To create an on-demand TPU VM instance, use the gcloud compute instances create command:

Important: When you use the ct6e-standard-8t machine type, you must set the threads per core to 1 by including the --threads-per-core=1 flag in the following command. For more information on threads per core, see Set the number of threads per core.

gcloud

gcloud compute instances create TPU_NAME \
  --machine-type=MACHINE_TYPE \
  --image-family=IMAGE_FAMILY \
  --image-project=IMAGE_PROJECT \
  --zone=ZONE \
  --maintenance-policy=TERMINATE

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TPU_NAME",
    "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"
        }
      }
    ],
    "scheduling": {
      "onHostMaintenance": "TERMINATE"
    },
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ]
  }' \
  "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances"

Replace the following placeholders:

• PROJECT_ID: The ID of your Google Cloud project.
• TPU_NAME: A name for your TPU VM.
• MACHINE_TYPE: The machine type for the TPU VM (for example ct6e-standard-8t).
• IMAGE_FAMILY: The OS image family for the TPU VM. If you want to install a specific OS version, use the --image flag. For more information about OS images, see OS images.
• IMAGE_PROJECT: The project that contains the OS image. For TPU images, this is ubuntu-os-accelerator-images.
• ZONE: The zone for the TPU VM (for example us-central1-b).

Create a TPU Spot VM instance

To create a TPU Spot VM instance, use the gcloud compute instances create command with the --provisioning-model=SPOT flag:

Important: When you use the ct6e-standard-8t machine type, you must set the threads per core to 1 by including the --threads-per-core=1 flag in the following command. For more information on threads per core, see Set the number of threads per core.

gcloud

gcloud compute instances create TPU_NAME \
  --machine-type=MACHINE_TYPE \
  --image-family=IMAGE_FAMILY \
  --image-project=IMAGE_PROJECT \
  --zone=ZONE \
  --provisioning-model=SPOT \
  --instance-termination-action=DELETE \
  --maintenance-policy=TERMINATE

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TPU_NAME",
    "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"
        }
      }
    ],
    "scheduling": {
      "onHostMaintenance": "TERMINATE",
      "provisioningModel": "SPOT",
      "instanceTerminationAction": "DELETE"
    },
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ]
  }' \
  "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances"

Replace the following placeholders:

• PROJECT_ID: The ID of your Google Cloud project.
• TPU_NAME: A name for your TPU VM.
• MACHINE_TYPE: The machine type for the TPU VM (for example ct6e-standard-8t).
• IMAGE_FAMILY: The OS image family for the TPU VM. If you want to install a specific OS version, use the --image flag. For more information about OS images, see OS images.
• IMAGE_PROJECT: The project that contains the OS image. For TPU images, this is ubuntu-os-accelerator-images.
• ZONE: The zone for the TPU VM (for example us-central1-b).

Create a TPU VM instance using a reservation

To create a TPU VM instance using the reservation-bound consumption option, use the gcloud compute instances create command with the --reservation-affinity=specific and --reservation flags:

Important: When you use the ct6e-standard-8t machine type, you must set the threads per core to 1 by including the --threads-per-core=1 flag in the following command. For more information on threads per core, see Set the number of threads per core.

gcloud

gcloud compute instances create TPU_NAME \
  --machine-type=MACHINE_TYPE \
  --image-family=IMAGE_FAMILY \
  --image-project=IMAGE_PROJECT \
  --zone=ZONE \
  --provisioning-model=reservation-bound \
  --reservation-affinity=specific \
  --reservation=RESERVATION_NAME \
  --instance-termination-action=DELETE \
  --maintenance-policy=TERMINATE

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TPU_NAME",
    "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"
        }
      }
    ],
    "scheduling": {
      "onHostMaintenance": "TERMINATE",
      "provisioningModel": "RESERVATION_BOUND",
      "instanceTerminationAction": "DELETE"
    },
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "reservationAffinity": {
      "consumeReservationType": "SPECIFIC_RESERVATION",
      "key": "compute.googleapis.com/reservation-name",
      "values": [
        "RESERVATION_NAME"
      ]
    }
  }' \
  "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances"

Replace the following placeholders:

• PROJECT_ID: The ID of your Google Cloud project.
• TPU_NAME: A name for your TPU VM.
• MACHINE_TYPE: The machine type for the TPU VM (for example ct6e-standard-8t).
• IMAGE_FAMILY: The OS image family for the TPU VM. If you want to install a specific OS version, use the --image flag. For more information about OS images, see OS images.
• IMAGE_PROJECT: The project that contains the OS image. For TPU images, this is ubuntu-os-accelerator-images.
• ZONE: The zone for the TPU VM (for example us-central1-b).
• RESERVATION_NAME: The name of your reservation.

Create a TPU Flex-start VM

To create a TPU Flex-start VM instance, use the gcloud compute instances create command with the --provisioning-model=FLEX_START flag:

Important: When you use the ct6e-standard-8t machine type, you must set the threads per core to 1 by including the --threads-per-core=1 flag in the following command. For more information on threads per core, see Set the number of threads per core.

gcloud

gcloud compute instances create TPU_NAME \
  --machine-type=MACHINE_TYPE \
  --image-family=IMAGE_FAMILY \
  --image-project=IMAGE_PROJECT \
  --zone=ZONE \
  --provisioning-model=FLEX_START \
  --max-run-duration=MAX_RUN_DURATION \
  --request-valid-for-duration=VALID_DURATION \
  --instance-termination-action=DELETE \
  --maintenance-policy=TERMINATE

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TPU_NAME",
    "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"
        }
      }
    ],
    "params": {
      "requestValidForDuration": {
        "seconds": VALID_DURATION
      }
    },
    "scheduling": {
      "onHostMaintenance": "TERMINATE",
      "provisioningModel": "FLEX_START",
      "instanceTerminationAction": "DELETE",
      "maxRunDuration": {
        "seconds": MAX_RUN_DURATION
      }
    },
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ]
  }' \
  "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances"

Replace the following placeholders:

• PROJECT_ID: The ID of your Google Cloud project.
• TPU_NAME: A name for your TPU VM.
• MACHINE_TYPE: The machine type for the TPU VM (for example ct6e-standard-8t).
• IMAGE_FAMILY: The OS image family for the TPU VM. If you want to install a specific OS version, use the --image flag. For more information about OS images, see OS images.
• IMAGE_PROJECT: The project that contains the OS image. For TPU images, this is ubuntu-os-accelerator-images.
• ZONE: The zone for the TPU VM (for example us-central1-b).
• MAX_RUN_DURATION: The maximum run duration for the TPU VM (for example 6h). For REST, specify this as a number of seconds (for example 21600 for 6 hours).
• VALID_DURATION: The maximum duration for which the request is valid. For REST, specify this as a number of seconds (for example 3600 for 1 hour). request is valid.

For more information about creating Compute Engine instances, see Create and start a Compute Engine instance.

What's next

• Learn how to Create a MIG with single-host Cloud TPU slices.
• Learn how to Create a MIG with a multi-host Cloud TPU slice.
• Learn how to manage TPU VMs.
• Learn about TPUs in GKE.
• Learn how to run an ML workload on TPUs, for example, Serve Qwen2-72B-Instruct with vLLM on TPUs.