Set up the Cloud TPU environment

Before you can use Cloud TPU resources to train or run inference on models, you need to do the following set up steps:

• Set up your Google Cloud project
• Set up your environment to use Cloud TPU
• Prepare to request a Cloud TPU

Set up your Google Cloud project

You must have a Google Cloud account and project to use Cloud TPU.

1. In the Google Cloud console, sign in to your Google Account or sign up for a new account.

2. Install the Google Cloud CLI. The Google Cloud CLI is an interface for accessing and managing Google Cloud resources and services.

   Note: If you need to use a particular release of gcloud CLI components, install these components to ensure that relevant commands and flags are supported. For example, for alpha components, run gcloud components install alpha.
   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

3. Select or create a Google Cloud project:

   In the Google Cloud console, select or create a Cloud project from the project selector.

   In the Cloud Shell, set your project ID using the gcloud CLI. The project ID is the name of your project shown in the Google Cloud console.

   $ gcloud config set project PROJECT-ID
   

4. Make sure that billing is enabled for your Google Cloud project.

   Billing setup is required for all Google Cloud usage. You will only be charged after you start using Google Cloud resources. For more information, see the Cloud Billing documentation.

   Billing for all Cloud TPU versions usage follows the standard regional pricing shown on the Cloud TPU pricing page.

Set up your environment to use Cloud TPU

Before requesting a Cloud TPU, you must activate the Cloud TPU API and ensure that you have permissions to manage access in your project and to create a Cloud TPU. It is also recommended that you create a user-managed service account to attach to your TPU.

1. Activate the Cloud TPU API from the Google Cloud console or using the gcloud CLI in the Cloud Shell:

   gcloud

   $ gcloud services enable tpu.googleapis.com
   

   Console

   1. In the Google Cloud console, go to the Cloud TPU API page.

   Go to the Cloud TPU API page

   1. Click Enable.

2. Make sure you have the following roles on your project:

   • Service Account Admin: Needed to create a service account
   • Project IAM Admin: Needed to grant a role in a project
   • TPU Admin: Needed to create a TPU

   Follow the instructions in View current access to view who has access to your project, folder, or organization. To view your own access, in the Principal column, find the row that has your email address. If your email address isn't in that column, then you don't have any roles. In the Role column for the row with your email address, check whether the list of roles includes the required roles.

   If you don't have a required role, grant the role or ask an administrator to do so.

3. Create a Cloud TPU service agent:

   Service agents, a type of service identity, are Google-maintained service identities that are used by the Cloud TPU service to perform operations in your Google Cloud project. For example, the service agent is used to create and manage Cloud TPU resources.

     $ gcloud beta services identity create --service tpu.googleapis.com --project $PROJECT_ID
   

4. Create a TPU service account:

   Service accounts act as credentials for your TPU VMs. Roles attached to a service account grant access to Google Cloud resources. We recommend using a user-managed service account, granting only the permissions required by your TPU VM. When using a user-managed service account, you must specify it when you are creating a TPU VM using the --service-account flag.

   1. Follow the instructions in Create service accounts to create a user-managed service account.

   2. Follow the instructions in Manage access to projects, folders, and organizations to grant your service account access to Google Cloud services that your TPU will access. The following roles are recommended so that your TPU to access commonly-used Google Cloud services.

      • TPU Admin: Needed for full access to TPU resources
      • Storage Admin: Needed for accessing Cloud Storage
      • Logs Writer: Needed for writing logs with the Logging API
      • Monitoring Metric Writer: Needed for writing metrics to Cloud Monitoring
   Note: If you don't specify a custom service account, your TPU uses the default Compute Engine service account.

Prepare to create a Cloud TPU

Before creating a Cloud TPU, you must request quota. You should also consider using queued resources, as well as which parameters you want to use to configure your TPU.

1. Request quota:

   In order to create a Cloud TPU, your Google Cloud project must have quota for the version and size of TPU you want to create and the zone where you want to create it. For example, if you want to create a TPU v4-8 in us-central2-b, you would request a quota of 8 TPU v4 cores in us-central2-b. For more information about zones where Cloud TPU is available, see TPU regions and zones.

   Quota is allocated differently depending on the TPU version. Different types of quota have different availability expectations. For more information about quota allocation, quota types, and how to request quota, see Quotas.

2. Determine if you want to use queued resources.

   Creating a Cloud TPU as a queued resource is a best practice. Queued resources allow you to receive capacity once it becomes available. You can specify an optional start and end time for when the request should be filled.

   There are different gcloud CLI commands for working with queued resources. For more information, see Queued resources user guide.

3. Determine Cloud TPU creation parameters:

   • Zone: Set the --zone flag to the zone where you want to create a TPU. You must have quota allocated in this zone. For more information, see TPU regions and zones.

   • TPU configuration: If you don't need to specify a custom topology, or you are using TPU v2 or v3, set the --accelerator-type flag to vVERSION-TENSORCORES. Replace VERSION with the TPU version number you want to use. Replace TENSORCORES with the number of TensorCores you want to use.

     If you want to customize the physical topology of your TPU, use the --version and --topology flags. Set the --version flag to the TPU version you want to use. Set the --topology flag to the topology you want to use.

     For more information about TPU configurations, including supported configurations and topology variants, see TPU versions.

   • Software version: If you are requesting a queued resource, set the --runtime-version flag to the name of the software version you want to use. Otherwise, use the --version flag. TPU software versions are available for TensorFlow, PyTorch, and JAX frameworks. For more information about supported software versions, see TPU VM software versions.

   • Service account: Set --service-account to the email address of a service account, if you created one, to attach the service account to your TPU. If empty, the default Compute Engine service account will be used.

   • Quota type: Add the flag that corresponds with the quota type you want to use:

     Quota type	Flag
     Reserved	--reserved
     Spot VMs	--spot
     Preemptible (not available for queued resources; use --spot instead)	--preemptible
     On-demand	No additional flag needed

   • Advanced configuration: You can add additional flags to your request to configure your TPU. See the gcloud compute tpus tpu-vm create documentation and the following sections for more information:

     • Run a startup script
     • Specify a network and subnetwork
     • Make IP addresses internal
     • Set an allocation interval for a queued resource request

For examples of how to create a Cloud TPU, see Get started.

What's next

1. Learn how to create and manage VM and TPU resources
2. Run a Cloud TPU quickstart