These concepts will be frequently used throughout this guide:
Host Project: A project that contains one or more Shared VPC
networks. In this guide, this project will contain your Shared VPC.
Service Project: A project attached to a Host Project by a
Shared VPC administrator. This attachment allows it to participate
in the Shared VPC. In this guide, this project will contain your
Cloud TPU cluster.
Requirements
Enable APIs
Enable the following APIs on the Google Cloud console for your
Host Project:
Setup IP range for VPC Peering to Google managed services
Follow these steps to reserve an IP range in the Shared VPC network in
the Host Project. The range will be used by all Google managed services
in this VPC network. Cloud TPU is one of the Google
managed services.
List existing IP ranges in the Shared VPC network.
[[["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-09-04 UTC."],[],[],null,["# GKE Cluster with Cloud TPU using a Shared VPC\n=============================================\n\n| **Warning:** The content in this document only applies to TPUs using the [TPU Node architecture](/tpu/docs/system-architecture-tpu-vm#tpu-arch). The TPU Node architecture is only supported in GKE on TPU v2 and v3. If you are using the [TPU VM architecture](/tpu/docs/system-architecture-tpu-vm#tpu-arch), see [Run TPU applications on Google Kubernetes Engine (GKE)](/tpu/docs/kubernetes-engine-setup).\n\nThis guide describes how to:\n\n- Set up a Cloud TPU [GKE](/kubernetes-engine/docs/concepts/kubernetes-engine-overview) cluster using a [Shared VPC](/vpc/docs/shared-vpc) network.\n- Setup the required [APIs](#apis) and [IP ranges](#ip-vpc-peering) to ensure communication between the cluster, the Shared VPC, and Google Managed Services.\n- Create [secondary CIDR ranges](#ip-secondary-ranges) for cluster pods and services.\n\n\nConcepts\n--------\n\nThese concepts will be frequently used throughout this guide:\n\n- **Host Project**: A project that contains one or more Shared VPC\n networks. In this guide, this project will contain your Shared VPC.\n\n- **Service Project**: A project attached to a Host Project by a\n Shared VPC administrator. This attachment allows it to participate\n in the Shared VPC. In this guide, this project will contain your\n Cloud TPU cluster.\n\nRequirements\n------------\n\n| **Note:** Your cluster must use GKE version **1.11.3-gke.18** or later.\n\nEnable APIs\n-----------\n\n1. Enable the following APIs on the Google Cloud console for your\n **Host Project**:\n\n - [Service Networking API](https://console.cloud.google.com/apis/library/servicenetworking.googleapis.com)\n2. Enable the following APIs on the Google Cloud console for your\n **Service Project**:\n\n - [Service Networking API](https://console.cloud.google.com/apis/library/servicenetworking.googleapis.com)\n - [Cloud TPU API](https://console.cloud.google.com/apis/library/tpu.googleapis.com)\n\nSetup IP range for VPC Peering to Google managed services\n---------------------------------------------------------\n\n| **Note:** These steps must be performed by a network administrator ([compute.networkAdmin](/compute/docs/access/iam#compute.networkAdmin) role) of the Host Project.\n\nFollow these steps to reserve an IP range in the Shared VPC network in\nthe **Host Project**. The range will be used by all Google managed services\nin this VPC network. Cloud TPU is one of the Google\nmanaged services.\n\n1. List existing IP ranges in the Shared VPC network.\n\n ```bash\n $ gcloud beta compute networks list-ip-addresses network \\\n --project=host-project-id\n ```\n2. Choose an available range and reserve it in the Shared VPC network.\n\n ```bash\n $ gcloud beta compute addresses create peering-name \\\n --global \\\n --prefix-length=16 \\\n --network=network \\\n --purpose=VPC_PEERING \\\n --project=host-project-id\n ```\n\n The \u003cvar translate=\"no\"\u003epeering-name\u003c/var\u003e specifies the name of the VPC Peering\n connection. The name will be used in the next step.\n3. Create a VPC Network Peering connection between the Host Project and\n Google managed services.\n\n ```bash\n $ gcloud beta services vpc-peerings connect \\\n --service=servicenetworking.googleapis.com \\\n --network=network \\\n --ranges=peering-name \\\n --project=host-project-id\n ```\n\nCreate secondary IP ranges for the cluster\n------------------------------------------\n\n| **Note:** These steps must be performed by a network admin ([compute.networkAdmin](/compute/docs/access/iam#compute.networkAdmin) role) of the Host Project.\n\nIn your Shared VPC network, select or create a subnetwork and add two\nsecondary CIDR ranges for the cluster pods and services.\n\n- [Create a VPC subnet with secondary CIDR ranges](/vpc/docs/configure-alias-ip-ranges#creating_a_subnet_with_one_or_more_secondary_cidr_ranges)\n\n- [Add secondary CIDR ranges to an existing VPC subnet](/vpc/docs/configure-alias-ip-ranges#adding_secondary_cidr_ranges_to_an_existing_subnet)\n\nThese ranges are for your cluster's pods and services, respectively. The range\nnames will be used in the following steps.\n\n- \u003cvar translate=\"no\"\u003esubnet\u003c/var\u003e will be the subnetwork in the \u003cvar translate=\"no\"\u003enetwork\u003c/var\u003e\n of your Host Project.\n\n- \u003cvar translate=\"no\"\u003etier-1-name\u003c/var\u003e will be the name of the secondary range used by\n GKE Pods in \u003cvar translate=\"no\"\u003esubnet\u003c/var\u003e.\n\n- \u003cvar translate=\"no\"\u003etier-2-name\u003c/var\u003e will be the name of the secondary range used by\n GKE Services in \u003cvar translate=\"no\"\u003esubnet\u003c/var\u003e.\n\nCreate a GKE cluster with Cloud TPU\n-----------------------------------\n\nThe following command shows how to create a GKE using the\nexisting CIDR ranges in your Shared VPC network, enabling\nCloud TPU: \n\n```bash\n$ gcloud beta container clusters create cluster-name \\\n --enable-ip-alias \\\n --network projects/host-project-id/global/networks/network \\\n --subnetwork projects/host-project-id/regions/region/subnetworks/subnet \\\n --cluster-secondary-range-name tier-1-name \\\n --services-secondary-range-name tier-2-name \\\n --scopes=cloud-platform \\\n --enable-tpu \\\n --enable-tpu-service-networking \\\n --project=service-project-id\n```\n\n- Refer to [`gcloud beta container clusters create`](/sdk/gcloud/reference/beta/container/clusters/create) command reference guide for further details on these flags.\n\nFollow the Pod Spec steps in the guide\n[Run Cloud TPU applications on GKE](/tpu/docs/kubernetes-engine-setup#job-spec)\nto build a job that uses Cloud TPU resources.\n\nClean Up\n--------\n\nWhen you've finished with Cloud TPU on GKE,\nclean up the resources to avoid incurring extra charges to your Cloud Billing\naccount.\n\n1. Delete the reserved peering IP range.\n\n ```bash\n $ gcloud beta compute addresses delete peering-name \\\n --global \\\n --project=host-project-id\n ```\n2. Follow the instructions on\n [Cleaning up](/kubernetes-engine/docs/how-to/cluster-shared-vpc#cleaning_up)\n on Setting up Clusters with Shared VPC to delete the cluster and the\n network resources."]]
