Stay organized with collections
Save and categorize content based on your preferences.
Use a cross-project service account
This document outlines how to use a cross-project service account when
creating a TPU VM. A cross-project service account is a service account
that is located in a different project than the TPU VM.
Note, the following instructions don't take Shared VPC or VPC Service Controls
into consideration. Additional configurations or permissions may 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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Use a cross-project service account\n===================================\n\nThis document outlines how to use a cross-project service account when\ncreating a TPU VM. A cross-project service account is a service account\nthat is located in a different project than the TPU VM.\n\nNote, the following instructions don't take Shared VPC or VPC Service Controls\ninto consideration. Additional configurations or permissions may be required to\nsupport their use. For more information, see [Create and modify Shared VPC networks](/vpc/docs/create-modify-vpc-networks)\nand [Overview of VPC Service Controls](/vpc-service-controls/docs/overview).\n\nBefore you begin\n----------------\n\n- 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](/resource-manager/docs/creating-managing-projects).\n- Create a service account in the `service_project`. For more information, see [Creating and managing service accounts](/iam/docs/creating-managing-service-accounts).\n- Create a network and enable Private Google Access. For more information, see [Creating and managing networks](/vpc/docs/create-modify-vpc-networks) and [Configure Private Google Access for an internal IP address](/vpc/docs/configure-private-google-access).\n- Disable the following organization policies. For more information, see [Organization policy constraints](/resource-manager/docs/organization-policy/org-policy-constraints).\n - `constraints/iam.disableCrossProjectServiceAccountUsage` in both projects\n - `constraints/compute.vmExternalIpAccess` (for accessing the VM with SSH, optional)\n\nDefine environment variables\n----------------------------\n\n```bash\nexport TPU_PROJECT_ID=tpu-project-id\nexport SERVICE_PROJECT_ID=service-project-id\nexport SERVICE_ACCOUNT_EMAIL=your_service_account@$(SERVICE_PROJECT_ID).iam.gserviceaccount.com\nexport ZONE=your-zone\nexport TPU_NAME=your-tpu-name\nexport NETWORK=your-network\nexport SUBNET=your-subnet\n```\n\nSet IAM permissions\n-------------------\n\n1. Allow your service account to use the TPU Service Agent role in the `tpu_project`.\n\n ```bash\n gcloud projects add-iam-policy-binding ${TPU_PROJECT_ID} \\\n --member=serviceAccount:${SERVICE_ACCOUNT_EMAIL} \\\n --role=roles/cloudtpu.serviceAgent\n ```\n2. Add the serviceAccountUser role to the TPU Service Agent.\n\n ```bash\n gcloud projects add-iam-policy-binding $SERVICE_PROJECT_ID \\\n --member=serviceAccount:service-$TPU_PROJECT_ID@gcp-sa-tpu.iam.gserviceaccount.com \\\n --role=roles/iam.serviceAccountUser\n ```\n3. If your workload is running in Docker containers, allow the Compute Engine\n Service Agent to access the metadata server.\n\n ```bash\n gcloud iam service-accounts add-iam-policy-binding \\\n --project $SERVICE_PROJECT_ID $SERVICE_ACCOUNT_EMAIL \\\n --role roles/iam.serviceAccountTokenCreator \\\n --member serviceAccount:service-$TPU_PROJECT_ID@compute-system.iam.gserviceaccount.com\n ```\n\nCreate a TPU VM in the `tpu_project`\n------------------------------------\n\nCreate a TPU VM in the `tpu_project` using the service account in the `service_project`. \n\n```bash\ngcloud alpha compute tpus tpu-vm create $TPU_NAME \\\n --description=$TPU_NAME \\\n --accelerator-type=v5litepod-8 \\\n --version=tpu-vm-tf-2.17.0-pod \\\n --network=projects/$PROJECT_A/global/networks/$NETWORK \\\n --subnetwork=$SUBNET \\\n --internal-ips \\\n --service-account=$SERVICE_ACCOUNT_EMAIL \\\n --project=$TPU_PROJECT_ID \\\n --zone=$ZONE\n```"]]
