# Create a TPU instance

This document shows you how to create a TPU v6e (Trillium) virtual machine (VM)
instance, connect to it, and run a calculation on it. The TPU instance that you
create in this quickstart uses on-demand, the default consumption option.

## Before you begin

<br />

### Required roles


To get the permissions that
you need to create a TPU instance, connect to it using SSH, and run commands,

ask your administrator to grant you the
following IAM roles on your project:

- [Compute Instance Admin (v1)](https://docs.cloud.google.com/iam/docs/roles-permissions/compute#compute.instanceAdmin.v1) (`roles/compute.instanceAdmin.v1`)
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`)
- [Service Usage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage#serviceusage.serviceUsageAdmin) (`roles/serviceusage.serviceUsageAdmin`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Create a TPU v6e (Trillium) instance

Run the following commands in your local terminal or using
[Cloud Shell](https://docs.cloud.google.com/shell/docs/launching-cloud-shell).

1. To create a TPU v6e instance, run the following [`gcloud compute instances
   create` command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/instances/create):

       gcloud compute instances create quickstart-tpu \
           --machine-type=ct6e-standard-4t \
           --zone=europe-west4-a \
           --image-project=ubuntu-os-accelerator-images \
           --image-family=ubuntu-accel-2204-amd64-tpu-v5e-v5p-v6e \
           --maintenance-policy=TERMINATE

2. Optionally, verify that the instance is running by using the [`gcloud
   compute instances describe`
   command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/instances/describe):

       gcloud compute instances describe quickstart-tpu --zone=europe-west4-a

   In the output, check the `status` field to verify if the instance is running
   or still pending.

## Connect to the TPU instance

You can connect to a TPU instance using the Google Cloud console or the
gcloud CLI.

To connect to the VM using SSH, run the following [`gcloud compute
ssh` command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/ssh):

    gcloud compute ssh quickstart-tpu --zone=europe-west4-a

## Install JAX

Install the JAX framework by running the following command on your TPU instance:

    pip install jax[tpu] -f https://storage.googleapis.com/jax-releases/libtpu_releases.html

> [!NOTE]
> **Note:** If this command fails, you might need to run `sudo apt update` and `sudo
> apt install python3-pip`.

## Run a system check

Verify that JAX can access the TPU and can run basic operations by running the
following commands on your TPU instance:

1. Start the Python 3 interpreter:

       python3

2. Import the JAX module:

       >>> import jax

3. Display the number of TPU cores available:

       >>> jax.device_count()

   The output shows the number of TPU cores. The number of cores is dependent
   on the TPU version you are using. For more information, see [TPU
   versions](https://docs.cloud.google.com/tpu/docs/system-architecture-tpu-vm#versions).

## Perform a calculation

1. Run the following command to add two numbers together:

       >>> jax.numpy.add(1, 1)

   The output should be similar to the following:

       >>> Array(2, dtype=int32, weak_type=True)

2. Exit the Python interpreter:

       >>> 
       exit()

## Clean up


To avoid incurring charges to your Google Cloud account for
the resources used on this page, delete the Google Cloud project with the
resources.

Alternatively, if you want to keep your project, you can delete only the VM by
using the [`gcloud compute instances delete`
command](https://docs.cloud.google.com/sdk/gcloud/reference/compute/instances/delete):

    gcloud compute instances delete quickstart-tpu --zone=europe-west4-a

## What's next

- Learn about [TPU resources in Compute Engine](https://docs.cloud.google.com/compute/docs/tpus/tpu-resources-in-compute-engine)
- [Create a TPU instance using other consumption options](https://docs.cloud.google.com/compute/docs/tpus/create-tpu-vm-instance)
- Learn about [TPU instances in MIGs](https://docs.cloud.google.com/compute/docs/tpus/tpus-and-migs)