This documentation is for the Latest version of Cloud Run for Anthos, which uses Anthos fleets and Anthos Service Mesh. Learn more.

The past version has been archived but the documentation remains available for existing users.

Using Workload Identity

Learn how to authenticate your Cloud Run for Anthos services with Workload Identity to access Google Cloud APIs such as the Compute APIs, Storage and Database APIs, or Machine Learning APIs.

To authenticate your Cloud Run for Anthos services, you must enable Workload Identity in your cluster, configure permissions, bind your Kubernetes Service Account (KSA) to a Google Service Account (GSA), and then you can configure each service for which you want to use that Workload Identity.

Enabling Workload Identity on your cluster

Instead of using a Google Cloud Service Account JSON file, to set up Workload Identity with Cloud Run for Anthos, you can setup fleet Workload Identity.

Enabling all metrics with Workload Identity

To enable metrics, like reporting request count or request latency to Google Cloud's operations suite, you need to grant write permissions for Cloud Monitoring. For example, you can grant the Monitoring Metric Writer role to the Google Service Account that is associated with Cloud Run for Anthos because it includes the necessary permissions for writing monitoring data.

See Using service accounts for more information about creating Google Service Accounts.

To grant the Monitoring Metric Writer role to your Google Service Account:

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

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

kubectl annotate serviceaccount \
    --namespace knative-serving controller \
    iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com

Replace:

  • PROJECT_ID with the ID of the Google Cloud project for the cluster where your Kubernetes Service Account and Cloud Run for Anthos services reside.
  • GSA_NAME@GSA_PROJECT_ID with the name of your Google Service Account and ID of the Google Cloud project. You can use any Google Service Account in your organization. To view your Google Service Accounts, see Listing your Google Service Accounts.

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 that you bind, automatically authenticates as the GSA when accessing Google Cloud APIs. The KSA that you bind must exist within the cluster and namespace of the Cloud Run for Anthos service for which you want to use Workload Identity. The GSA can belong to a different Google Cloud project from the Cloud project where the cluster resides.

  1. If a Google Service Account doesn't exist, create one; otherwise, skip to the next step. You can create a GSA for use with Cloud Run for Anthos within any Google Cloud project in your organization and then use it from in the Google Cloud project where your Cloud Run for Anthos services run.

    To create a new GSA, run the following command:

    gcloud iam service-accounts create GSA_NAME

    Replace GSA_NAME with the name of the new Google service account.

    For more information about using Google service accounts with your Cloud Run for Anthos services, see Using service accounts.

  2. Ensure that your GSA has the IAM roles that you need. You can grant additional roles using the following command:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member "serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role "ROLE_NAME"
    

    Replace:

    • PROJECT_ID: with the Google Cloud project ID where your Google Service Account resides.
    • GSA_NAME with the name of your Google Service Account.
    • ROLE_NAME with the IAM role to assign to your GSA, like roles/monitoring.metricWriter.
  3. If a Kubernetes Service Account doesn't exist, create one in the same Kubernetes namespace as your Cloud Run for Anthos service; otherwise, skip to the next step:

    kubectl create serviceaccount --namespace K8S_NAMESPACE KSA_NAME
  4. Bind the Kubernetes and Google service accounts to create the Workload Identity and then deploy it to your cluster:

    1. Allow the KSA to impersonate the GSA by creating an IAM policy binding between the two.

      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_ID.iam.gserviceaccount.com

      Replace:

      • PROJECT_ID with the ID of the Google Cloud project for the cluster where your Kubernetes Service Account and Cloud Run for Anthos services reside.
      • K8S_NAMESPACE/KSA_NAME with the namespace and name of your Kubernetes Service Account.
      • GSA_NAME@GSA_PROJECT_ID with the name of your Google Service Account and ID of the Google Cloud project. You can use any Google Service Account in your organization. To view your Google Service Accounts, see Listing service accounts.
    2. Add the iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT_ID annotation to the KSA, using the email address of the GSA.

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

      Replace:

      • K8S_NAMESPACE/KSA_NAME with the namespace and name of the Kubernetes Service Account for which you created a binding.
      • GSA_NAME@GSA_PROJECT_ID with the name of your Google Service Account and ID of the Google Cloud project for which you created a binding.

Deploying a new service to use Workload Identity

Deploy a new Cloud Run for Anthos service that uses the Workload Identity you created.

Console

  1. Go to Cloud Run for Anthos in the Cloud Console:

    Go to Cloud Run for Anthos

  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.

    image

  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 Cloud Run for Anthos and wait for the deployment to finish.

Command line

  • For existing services, set the Kubernetes Service Account by running the gcloud run services update command with the following parameters:

    gcloud run services update SERVICE --service-account KSA_NAME
    

    Replace:

    • SERVICE with the name of your Cloud Run for Anthos service.
    • KSA_NAME with the Kubernetes Service Account that you used to create the Workload Identity.
  • For new services, set the Kubernetes Service Account by running the gcloud run deploy command with the --service-account parameter:

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

    Replace:

    • IMAGE_URL with a reference to the container image, for example, gcr.io/cloudrun/hello.
    • KSA_NAME with the Kubernetes Service Account that you used to create the Workload Identity.

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 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 Cloud Run for Anthos service.

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

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

    Replace

    • SERVICE with the name of your Cloud Run for Anthos service.
    • KSA_NAME with the Kubernetes Service Account that you used to create the Workload Identity.
  3. Deploy the configuration to your Cloud Run for Anthos service by running the following command:

    gcloud run services replace service.yaml

Migrating existing services to use Workload Identity

If you enabled Workload Identity on an existing cluster, each service on that cluster for which you want to use Workload Identity must be migrated. Learn how to migrate existing services.

Next steps

Learn how to manage access to your services.