Using Workload Identity

This page explains how to authenticate your Knative serving service to use Google Cloud APIs by enabling Workload Identity.

To use Google Cloud APIs such 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 enabling Workload Identity and 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:

Enable Workload Identity on a new cluster or Enable Workload Identity on an existing cluster

Enabling metrics on a cluster with Workload Identity

When enabling Workload 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 the Google service account (GSA) associated with your Knative serving service.

Grant the Monitoring Metric Writer role permissions to your service's GSA:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \
--role=roles/monitoring.metricWriter

Replace:

• PROJECT_ID with the project ID for a cluster project that hosts your KSA.
• GSA_PROJECT with the project ID for a GSA that's not in the cluster. You can use any GSA in your organization.

For more information, see Granting, changing, and revoking access to resources.

Binding service accounts

You need to set up a relationship for a Kubernetes service account (KSA) to act as a Google service account (GSA). Any workload running as the KSA automatically authenticates as the GSA when accessing Google Cloud APIs.

1. If a Kubernetes service account (KSA) doesn't exist, create one in the same Kubernetes namespace as your Knative serving service; otherwise, skip to the next step:

   kubectl create serviceaccount --namespace K8S_NAMESPACE KSA_NAME

2. 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:

   1. Authorize your KSA to act as a GSA:

      gcloud iam service-accounts add-iam-policy-binding \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]" \
      GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com

   2. Update the cluster to leverage the binding:

      kubectl annotate serviceaccount \
      --namespace K8S_NAMESPACE \
       KSA_NAME \
       iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com

Deploying a new service with a new identity

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

1. Go to Knative serving in the Google Cloud console:

   Go to Knative serving

2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit & Deploy New Revision.

3. Under Advanced settings, click Container.

   

4. Click the Service account dropdown and select the desired service account.

5. Click Next to continue to the next section.

6. In the Configure how this service is triggered section, select which connectivity you would like to use to invoke the service.

7. Click Create to 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 the gcloud run services update command with the following parameters:

  gcloud run services update SERVICE --service-account SERVICE_ACCOUNT
  

  Replace:

  • SERVICE with the name of your service.
  • SERVICE_ACCOUNT with the service account associated with the new identity.

• For new services, configure the runtime service account by running the gcloud run deploy command with the --service-account parameter:

  gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT
  

  Replace:

  • IMAGE_URL with a reference to the container image, for example, gcr.io/myproject/my-image:latest.
  • SERVICE_ACCOUNT with the service account associated with the new identity.

YAML

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.

You can download the configuration of an existing service into a YAML file with the gcloud run services describe command by using the --format=export flag. You can then modify that YAML file and deploy those changes with the gcloud beta run services replace command. You must ensure that you modify only the specified attributes.

1. Download the configuration of your service into a file named service.yaml on local workspace:

   gcloud run services describe SERVICE --format export > service.yaml

   Replace SERVICE with the name of your Knative serving service.

2. In your local file, update the serviceAccountName: attribute:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         serviceAccountName: SERVICE_ACCOUNT

   Replace

   • SERVICE with the name of your Knative serving service.
   • SERVICE_ACCOUNT with the service account associated with the new identity.

3. Replace the service with its new configuration using the following command:

   gcloud beta run services replace service.yaml