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.
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
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:
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
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
Go to Knative serving in the Google Cloud console:
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.
Under Advanced settings, click Container.
Click the Service account dropdown and select the desired service account.
Click Next to continue to the next section.
In the Configure how this service is triggered section, select which connectivity you would like to use to invoke the service.
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.
- IMAGE_URL with a reference to the container image, for
example,
YAML
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.
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.
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.
Replace the service with its new configuration using the following command:
gcloud beta run services replace service.yaml