Stay organized with collectionsSave and categorize content based on your preferences.
Prepare to setup the Gateway API for Cloud Service Mesh
This page describes how to install the required custom resource definitions
for the gateway into your cluster.
Limitations
Having a mix ofgatewayconfig-api andistioconfig-api clusters in the
same fleet is not supported. Make sure the config-api is set togatewayfor
all the clusters in your fleet. Use thegcloud container fleet mesh describe --project FLEET_PROJECT_IDcommand to
see what you have configured for your fleet.
Multi-cluster service discovery and load balancing is not supported forgatewayconfig-api clusters.
If a cluster is onboarded using the existing--management automaticflag
then the cluster starts using theistioconfiguration API and cannot change
togatewayAPI.
Only FQDNs are supported. Short names are not supported.
Data plane management considerations
For new pods, Google manages which proxy version is injected. Note that the
managed data plane relies on the Google Kubernetes Engine (GKE) release channel to
determine the proxy version.
For existing pods, proxy management is done passively, driven by the natural
lifecycle of the pods in the cluster. To trigger the
update and re-inject new versions of the proxy, restart your workloads.
Sign in to your Google Cloud account. If you're new to
Google Cloud,create an accountto evaluate how our products perform in
real-world scenarios. New customers also get $300 in free credits to
run, test, and deploy workloads.
In the Google Cloud console, on the project selector page,
select or create a Google Cloud project.
NAME EXTERNAL_ID LOCATION
my-cluster 91980bb9-593c-4b36-9170-96445c9edd39 us-west1
Set up permissions
Note that the following commands grant permission to all authenticated users,
but you can use Workload Identity Federation for GKE to grant permission to only select accounts.
For details on how Workload Identity Federation for GKE works,
seeAbout Workload Identity Federation for GKE.
To configure Workload Identity Federation for GKE, seeAuthenticate to Google Cloud APIs from GKE workloads.
Set your fleet new memberships to use the Gateway API by default (optional)
Alternatively, you can createfleet-level default settingsfor new GKE clusters registered to the fleet during cluster creation to be automatically configured with Gateway API.
[[["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,["# Prepare to setup the Gateway API for Cloud Service Mesh\n=======================================================\n\nThis page describes how to install the required custom resource definitions\nfor the gateway into your cluster.\n\nLimitations\n-----------\n\n- Having a mix of `gateway` config-api and `istio` config-api clusters in the same fleet is not supported. Make sure the config-api is set to `gateway` for all the clusters in your fleet. Use the `gcloud container fleet mesh describe --project FLEET_PROJECT_ID` command to see what you have configured for your fleet.\n- Multi-cluster service discovery and load balancing is not supported for `gateway` config-api clusters.\n- If a cluster is onboarded using the existing `--management automatic` flag then the cluster starts using the `istio` configuration API and cannot change to `gateway` API.\n- Only FQDNs are supported. Short names are not supported.\n\nData plane management considerations\n------------------------------------\n\nFor new pods, Google manages which proxy version is injected. Note that the\nmanaged data plane relies on the Google Kubernetes Engine (GKE) release channel to\ndetermine the proxy version.\n\nFor existing pods, proxy management is done passively, driven by the natural\nlifecycle of the pods in the cluster. To trigger the\nupdate and re-inject new versions of the proxy, restart your workloads.\n\nPrerequisites\n-------------\n\nAs a starting point, this guide assumes that you have already\n[created a Google Cloud project](/sdk/docs/install-sdk#before-you-begin) and\n[installed `kubectl`](/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_kubectl).\n\nBefore you begin\n----------------\n\n- Sign in to your Google Cloud account. If you're new to Google Cloud, [create an account](https://console.cloud.google.com/freetrial) to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Kubernetes Engine, GKE Hub, and Cloud Service Mesh APIs.\n\n\n [Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=container.googleapis.com,gkehub.googleapis.com,mesh.googleapis.com)\n\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Kubernetes Engine, GKE Hub, and Cloud Service Mesh APIs.\n\n\n [Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=container.googleapis.com,gkehub.googleapis.com,mesh.googleapis.com)\n\n\u003cbr /\u003e\n\nCreate and register a GKE cluster\n---------------------------------\n\n### gcloud\n\n\nCreate a GKE cluster: \n\n gcloud container clusters create \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e \\\n --enable-ip-alias \\\n --scopes=https://www.googleapis.com/auth/cloud-platform \\\n --release-channel=regular \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --gateway-api=standard \\\n --workload-pool=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e.svc.id.goog \\\n --workload-metadata=GKE_METADATA\n\nwhere:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e is the name of your cluster\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e is the location of your cluster\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e is the project ID of your cluster\n\n### Console\n\n1. Go to the **Google Kubernetes Engine** page in the Google Cloud console.\n\n [Go to Google Kubernetes Engine](https://console.cloud.google.com/kubernetes/list)\n2. Click *add_box* **Create**.\n\n3. In the **Standard** section, click **Configure**.\n\n4. In the **Cluster basics** section, complete the following:\n\n 1. Enter the **Name** for your cluster.\n 2. For the **Location type** , select a [Compute Engine region](/compute/docs/regions-zones#available) for your cluster.\n5. In the navigation pane, click **default-pool** under **Node Pools**\n section, and select **Security**.\n\n6. In the **Access scopes** list, select **Set access for each API** , and\n set **Cloud Platform** as **Enabled**.\n\n7. In the navigation pane, click **Networking** under **Cluster** section.\n\n8. In the **Cluster Networking** list, select **Enable Gateway API**.\n\n9. In the navigation pane, click **Security** under **Cluster** section.\n\n10. In the **Security** list, select **Enable Workload Identity**.\n\n11. Click **Create**.\n\nAfter the cluster is created,\n\n1. Register your cluster to a [fleet](/kubernetes-engine/fleet-management/docs#introducing_fleets):\n\n gcloud container fleet memberships register \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --gke-cluster \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\n2. Verify that the cluster is registered to the fleet:\n\n gcloud container fleet memberships list --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\n The output is similar to: \n\n NAME EXTERNAL_ID LOCATION\n my-cluster 91980bb9-593c-4b36-9170-96445c9edd39 us-west1\n\nSet up permissions\n------------------\n\nNote that the following commands grant permission to all authenticated users,\nbut you can use Workload Identity Federation for GKE to grant permission to only select accounts.\nFor details on how Workload Identity Federation for GKE works,\nsee [About Workload Identity Federation for GKE](/kubernetes-engine/docs/concepts/workload-identity).\nTo configure Workload Identity Federation for GKE, see\n[Authenticate to Google Cloud APIs from GKE workloads](/kubernetes-engine/docs/how-to/workload-identity).\n\nGrant the `trafficdirector.client` role: \n\n gcloud projects add-iam-policy-binding \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --member \"group:\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e.svc.id.goog:/allAuthenticatedUsers/\" \\\n --role \"roles/trafficdirector.client\"\n\nEnable Cloud Service Mesh\n-------------------------\n\n1. Enable the mesh feature:\n\n gcloud container fleet mesh enable --project \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\n2. Update the mesh to use the Gateway API:\n\n gcloud alpha container fleet mesh update \\\n --config-api gateway \\\n --memberships \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --project \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\n3. Verify the update by describing the status of Cloud Service Mesh resource:\n\n gcloud alpha container fleet mesh describe \\\n --project \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\nSet your fleet new memberships to use the Gateway API by default (optional)\n---------------------------------------------------------------------------\n\nAlternatively, you can create [fleet-level default settings](/service-mesh/v1.25/docs/onboarding/provision-control-plane#configure_your_fleet) for new GKE clusters registered to the fleet during cluster creation to be automatically configured with Gateway API.\n\n1. Create a YAML file specifying using Gateway API:\n\n echo \"configapi: gateway\" \u003e mesh.yaml\n\n | **Note:** `management` and `config-api` shouldn't be configured at the same time.\n2. Update your mesh:\n\n gcloud alpha container fleet mesh update --project \u003cvar translate=\"no\"\u003eFLEET_PROJECT_ID\u003c/var\u003e \\\n --fleet-default-member-config mesh.yaml\n\n3. Create a cluster and register them to your fleet in one step to use the default configuration:\n\n gcloud container clusters create \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --project \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --fleet-project \u003cvar translate=\"no\"\u003eFLEET_PROJECT_ID\u003c/var\u003e \\\n --location=\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e \\\n\n4. Enable Workload Identity Federation for GKE and run the GKE Metadata Server on your node.\n\nInstall custom resource definitions\n-----------------------------------\n\nGenerate a kubeconfig entry for your cluster: \n\n```\ngcloud container clusters get-credentials CLUSTER_NAME --location LOCATION --project PROJECT_ID\n```\n\n\u003cbr /\u003e\n\nwhere:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e is the name of your cluster\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e is the location of your cluster\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e is the project ID of your cluster\n\nInstall the GRPCRoute custom resource definition (CRD): \n\n curl https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.1.0/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml \\\n | kubectl apply -f -\n\nThe output is similar to: \n\n customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created\n\nWhat's next\n-----------\n\n- [Set up an Envoy sidecar service mesh on GKE](/service-mesh/v1.25/docs/gateway/set-up-envoy-mesh)\n- [Set up a proxyless gRPC service mesh on GKE](/service-mesh/v1.25/docs/gateway/proxyless-grpc-mesh)"]]
