Use a cross-project service account

This document describes how to use a cross-project service account when creating a TPU VM. A cross-project service account is a service account that resides in a different project than the TPU VM.

These instructions do not include considerations for Shared VPC or VPC Service Controls. Additional configurations or permissions might be required to support their use. For more information, see Create and modify Shared VPC networks and Overview of VPC Service Controls.

Before you begin

Create two Google Cloud projects. One to contain the TPU VM (TPU_PROJECT) and one to contain the service account (SERVICE_PROJECT). For more information, see Creating and managing projects.
Create a service account in the SERVICE_PROJECT. For more information, see Creating and managing service accounts.
Create a network and enable Private Google Access. For more information, see Creating and managing networks and Configure Private Google Access for an internal IP address.
Disable the following organization policies. For more information, see Organization policy constraints.
- constraints/iam.disableCrossProjectServiceAccountUsage in both projects
- constraints/compute.vmExternalIpAccess (for accessing the VM with SSH, optional)

Set IAM permissions

Grant your user account the Service Account User role to let it attach the service account to the VM instance.
```
gcloud iam service-accounts add-iam-policy-binding \
  SERVICE_ACCOUNT_EMAIL \
  --project=SERVICE_PROJECT_ID \
  --member=user:USER_EMAIL \
  --role=roles/iam.serviceAccountUser
```
Replace the following placeholders:
- SERVICE_ACCOUNT_EMAIL: The email address of the service account.
- SERVICE_PROJECT_ID: The ID of the project that contains the service account.
- USER_EMAIL: The email address of the user account.
If your workload runs in Docker containers, grant the Compute Engine Service Agent access to the metadata server.
```
gcloud iam service-accounts add-iam-policy-binding \
  SERVICE_ACCOUNT_EMAIL \
  --project=SERVICE_PROJECT_ID \
  --role=roles/iam.serviceAccountTokenCreator \
  --member=serviceAccount:service-TPU_PROJECT_ID@compute-system.iam.gserviceaccount.com
```
Replace the following placeholders:
- SERVICE_ACCOUNT_EMAIL: The email address of the service account.
- SERVICE_PROJECT_ID: The ID of the project that contains the service account.
- TPU_PROJECT_ID: The ID of the project that contains the TPU VM.

Create a TPU VM in the TPU project

Create a TPU VM in the TPU project using the service account in the service project.

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

Replace the following placeholders:

TPU_NAME: The name of the TPU VM.
MACHINE_TYPE: The machine type.
IMAGE_FAMILY: The OS image family for the TPU VM. To install a specific OS version, use the --image flag.
IMAGE_PROJECT: The project that contains the OS image. For TPU images, this is ubuntu-os-accelerator-images.
SERVICE_ACCOUNT_EMAIL: The email address of the service account.
TPU_PROJECT_ID: The ID of the project that contains the TPU VM.
ZONE: The zone of the TPU VM.