Stay organized with collectionsSave and categorize content based on your preferences.
This page explains how to authenticate your Knative serving service to
use Google Cloud APIs by enabling Workload Identity.
To useGoogle Cloud APIssuch as the Compute APIs, Storage and
Database APIs, or Machine Learning APIs from within your
GKE cluster, you must have permissions and authenticate
your Knative serving service by enablingWorkload Identityand binding a Kubernetes service account to act as a Google service account.
Enabling Workload Identity on your cluster
To set up Workload Identity with Knative serving, see the
following instructions to enable it on your cluster; otherwise, skip to the next
section:
Enabling metrics on a cluster with Workload Identity
When enablingWorkload Identity,
Knative serving doesn't report certain metrics, such as revision
request count or request latency to Google Cloud Observability, but continues reporting
metrics for CPU and memory.
To enable all metrics, you need to manually set permissions to write metrics to
Cloud Monitoring by granting the Monitoring Metric Writer role to theGoogle service account(GSA) associated with your
Knative serving service.
Grant the Monitoring Metric Writer role permissions to your service's GSA:
You need to set up a relationship for aKubernetes service
account(KSA) to act as aGoogle service account(GSA).
Any workload running as the KSA automatically authenticates as the GSA when
accessing Google Cloud APIs.
If aKubernetes service account (KSA)doesn't exist, create one in the same Kubernetes namespace as your
Knative serving service; otherwise, skip to the next step:
Create a relationship between KSAs and GSAs, so that the workload running as
the KSA automatically authenticates as the GSA when accessing Google Cloud
APIs:
Deploy your service using the KSA that exists within the cluster and namespace
of the service you want to deploy. The service account may belong to a
different project than the cluster.
Console
Go to Knative serving in the Google Cloud console:
ClickCreate Serviceif you are configuring a
new service you are deploying to. If you are configuring an
existing service, click on the service, then clickEdit & Deploy New Revision.
UnderAdvanced settings, clickContainer.
Click theService accountdropdown and select the desired service
account.
ClickNextto continue to the next section.
In theConfigure how this service is triggeredsection,
select which connectivity you would like to use to invoke the service.
ClickCreateto deploy the image to Knative serving and wait
for the deployment to finish.
Command line
For existing services, configure the runtime service account by running thegcloud run services updatecommand with the following parameters:
IMAGE_URLwith a reference to the container image, for
example,gcr.io/myproject/my-image:latest.
SERVICE_ACCOUNTwith the service account associated with the
new identity.
YAML
You can download the configuration of an existing service into a
YAML file with thegcloud run services describecommand by using the--format=exportflag.
You can then modify that YAML file and deploy
those changes with thegcloud beta run services replacecommand.
You must ensure that you modify only the specified attributes.
Download the configuration of your service into a file namedservice.yamlon local workspace:
[[["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."],[[["\u003cp\u003eThis guide outlines how to enable Workload Identity to authenticate your Knative serving service to utilize Google Cloud APIs, such as Compute, Storage, Database, and Machine Learning APIs.\u003c/p\u003e\n"],["\u003cp\u003eEnabling Workload Identity on your cluster is a prerequisite, and instructions are provided for both new and existing clusters.\u003c/p\u003e\n"],["\u003cp\u003eTo ensure comprehensive metrics are reported to Google Cloud Observability, including revision request count and latency, you must manually grant the Monitoring Metric Writer role to the Google service account (GSA) associated with your Knative service.\u003c/p\u003e\n"],["\u003cp\u003eA Kubernetes service account (KSA) must be bound to a Google service account (GSA) to allow workloads running as the KSA to automatically authenticate as the GSA when accessing Google Cloud APIs.\u003c/p\u003e\n"],["\u003cp\u003eDeploying a service with a new identity can be done via the Google Cloud console, command line, or YAML, where you need to configure the runtime service account in order to associate the identity.\u003c/p\u003e\n"]]],[],null,["# Using Workload Identity\n\nThis page explains how to authenticate your Knative serving service to\nuse Google Cloud APIs by enabling Workload Identity.\n\nTo use [Google Cloud APIs](/apis) such as the Compute APIs, Storage and\nDatabase APIs, or Machine Learning APIs from within your\nGKE cluster, you must have permissions and authenticate\nyour Knative serving service by enabling [Workload Identity](/kubernetes-engine/docs/how-to/workload-identity)\nand binding a Kubernetes service account to act as a Google service account.\n\nEnabling Workload Identity on your cluster\n------------------------------------------\n\nTo set up Workload Identity with Knative serving, see the\nfollowing instructions to enable it on your cluster; otherwise, skip to the next\nsection:\n\n[Enable Workload Identity on a new cluster](/kubernetes-engine/docs/how-to/workload-identity#enable_on_new_cluster)\nor [Enable Workload Identity on an existing cluster](/kubernetes-engine/docs/how-to/workload-identity#enable_on_existing_cluster)\n\nEnabling metrics on a cluster with Workload Identity\n----------------------------------------------------\n\nWhen enabling [Workload Identity](/kubernetes-engine/docs/how-to/workload-identity),\nKnative serving doesn't report certain metrics, such as revision\nrequest count or request latency to Google Cloud Observability, but continues reporting\nmetrics for CPU and memory.\n\nTo enable all metrics, you need to manually set permissions to write metrics to\nCloud Monitoring by granting the Monitoring Metric Writer role to the\n[Google service account](/iam/docs/service-accounts) (GSA) associated with your\nKnative serving service.\n\nGrant the Monitoring Metric Writer role permissions to your service's GSA: \n\n```bash\ngcloud projects add-iam-policy-binding PROJECT_ID \\\n--member=serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \\\n--role=roles/monitoring.metricWriter\n```\n\nReplace:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e with the project ID for a cluster project that hosts your KSA.\n- \u003cvar translate=\"no\"\u003eGSA_PROJECT\u003c/var\u003e with the project ID for a GSA that's not in the cluster. You can use any GSA in your organization.\n\nFor more information, see [Granting, changing, and revoking access to resources](/iam/docs/granting-changing-revoking-access).\n\nBinding service accounts\n------------------------\n\nYou need to set up a relationship for a [Kubernetes service\naccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/)\n(KSA) to act as a [Google service account](/iam/docs/service-accounts) (GSA).\nAny workload running as the KSA automatically authenticates as the GSA when\naccessing Google Cloud APIs.\n\n1. If a [Kubernetes service account (KSA)](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/)\n doesn't exist, create one in the same Kubernetes namespace as your\n Knative serving service; otherwise, skip to the next step:\n\n ```\n kubectl create serviceaccount --namespace K8S_NAMESPACE KSA_NAME\n ```\n2. Create a relationship between KSAs and GSAs, so that the workload running as\n the KSA automatically authenticates as the GSA when accessing Google Cloud\n APIs:\n\n 1. Authorize your KSA to act as a GSA:\n\n ```\n gcloud iam service-accounts add-iam-policy-binding \\\n --role roles/iam.workloadIdentityUser \\\n --member \"serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]\" \\\n GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com\n ```\n 2. Update the cluster to leverage the binding:\n\n ```\n kubectl annotate serviceaccount \\\n --namespace K8S_NAMESPACE \\\n KSA_NAME \\\n iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com\n ```\n\nDeploying a new service with a new identity\n-------------------------------------------\n\nDeploy your service using the KSA that exists within the cluster and namespace\nof the service you want to deploy. The service account may belong to a\ndifferent project than the cluster. \n\n### Console\n\n\n1. Go to Knative serving in the Google Cloud console:\n\n [Go to Knative serving](https://console.cloud.google.com/kubernetes/run)\n2. Click **Create Service** if you are configuring a\n new service you are deploying to. If you are configuring an\n existing service, click on the service, then click\n **Edit \\& Deploy New Revision**.\n\n3. Under *Advanced settings* , click **Container**.\n\n4. Click the **Service account** dropdown and select the desired service\n account.\n\n5. Click **Next** to continue to the next section.\n\n6. In the **Configure how this service is triggered** section,\n select which connectivity you would like to use to invoke the service.\n\n7. Click **Create** to deploy the image to Knative serving and wait\n for the deployment to finish.\n\n### Command line\n\n- For existing services, configure the runtime service account by running the\n [`gcloud run services update`](/sdk/gcloud/reference/run/services/update)\n command with the following parameters:\n\n ```bash\n gcloud run services update SERVICE --service-account SERVICE_ACCOUNT\n ```\n\n Replace:\n - \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with the name of your service.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e with the service account associated with the new identity.\n- For new services, configure the runtime service account by running the\n `gcloud run deploy` command with the\n [`--service-account`](/sdk/gcloud/reference/run/deploy#--service-account)\n parameter:\n\n ```bash\n gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT\n ```\n\n Replace:\n - \u003cvar translate=\"no\"\u003eIMAGE_URL\u003c/var\u003e with a reference to the container image, for example, `gcr.io/myproject/my-image:latest`.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e with the service account associated with the new identity.\n\n### YAML\n\n| **Caution:** Deploying configuration changes using YAML files replaces the configuration of your existing services. Since a YAML file completely overwrites all configurations, you should avoid using multiple methods to modify your services. For example, do not use YAML files in conjunction with the Google Cloud console or `gcloud` commands.\n\nYou can download the configuration of an existing service into a\nYAML file with the `gcloud run services describe` command by using the\n[`--format=export`](/sdk/gcloud/reference/run/services/describe) flag.\nYou can then modify that YAML file and deploy\nthose changes with the `gcloud beta run services replace` command.\nYou must ensure that you modify only the specified attributes.\n\n1. Download the configuration of your service into a file named\n `service.yaml` on local workspace:\n\n ```bash\n gcloud run services describe SERVICE --format export \u003e service.yaml\n ```\n\n Replace \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with the name of your\n Knative serving service.\n2. In your local file, update the `serviceAccountName:` attribute:\n\n ```yaml\n apiVersion: serving.knative.dev/v1\n kind: Service\n metadata:\n name: SERVICE\n spec:\n template:\n spec:\n serviceAccountName: SERVICE_ACCOUNT\n ```\n\n Replace\n - \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with the name of your Knative serving service.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e with the service account associated with the new identity.\n3. Replace the service with its new configuration using the following command:\n\n ```bash\n gcloud beta run services replace service.yaml\n ```"]]
