Use workload identity with Google Cloud

Workload identity enables you to assign distinct, fine-grained identities and authorization for each application in your cluster. Workload identity is the recommended way for applications running within GKE on AWS to access Google Cloud services. For more information, see Workload identity.

This topic describes how to use workload identity to connect to Google Cloud services from your workloads.

Configure a Google Cloud service account

In this section, you create a Google Cloud service account (GSA) with limited permissions to access Google Cloud services.

Get your workload identity pool and provider

To configure workload identity, you must have the values for your cluster's identity provider URI and workload identity pools.

  1. Determine the workload identity pool for your cluster:

    All GKE clusters have an identity provider created in the workload identity pool PROJECT_ID.svc.id.goog. To get your cluster's identity pool name, use the Google Cloud CLI:

    gcloud container aws clusters describe CLUSTER_NAME \
        --location=GOOGLE_CLOUD_LOCATION \
        --format='value(workloadIdentityConfig.workloadPool)'
    

    Replace the following:

    • CLUSTER_NAME with the name of your cluster.
    • GOOGLE_CLOUD_LOCATION with the name of the Google Cloud location that manages your cluster

    The output includes the name of your cluster's identity pool. Save this value. You'll need it later.

  2. Determine the identity provider for your cluster.

    To find your cluster's identity provider name, use the Google Cloud CLI:

    gcloud container aws clusters describe CLUSTER_NAME \
        --location=GOOGLE_CLOUD_LOCATION \
        --format='value(workloadIdentityConfig.identityProvider)'
    

    Replace the following:

    • CLUSTER_NAME
    • GOOGLE_CLOUD_LOCATION

    The output includes the name of your cluster's identity provider. Save this value. You'll need it later.

Create a Google Cloud service account

To create a Google Cloud service account (GSA), grant permissions to it, and add an IAM policy binding to the GSA, do these steps:

  1. Create the GSA with the Google Cloud CLI:

    gcloud iam service-accounts create GSA_NAME --project=PROJECT_ID
    

    Replace the following:

    • GSA_NAME: the name of the GSA for your application.
    • PROJECT_ID: the GSA's Google Cloud project.
  2. Add an IAM binding to allow the GSA to access services.

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

    Replace the following:

    • GSA_NAME: the name of the GSA for your application
    • PROJECT_ID: the project ID for the GSA
    • IAM_ROLE: the IAM role to grant to the GSA

    In this example, we will use the role roles/compute.viewer, which allows read-only access to compute services:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/compute.viewer
    
  3. Grant permissions for your Kubernetes service account (KSA) to impersonate the GSA. You do this by adding an IAM policy binding with the role roles/iam.workloadIdentityUser:

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

    Replace the following:

    • GSA_NAME
    • PROJECT_ID
    • NAMESPACE: the Kubernetes Namespace for the application
    • KSA_NAME: the KSA to use for the application

Deploy a sample application

In this section, you deploy a sample application that accesses the Compute Engine API. To Use this sample, your service account must have the roles/compute.viewer IAM role granted to it. To deploy the sample application, follow these steps:

  1. Copy the following manifest into a file named workload-identity-sample.yaml:

    apiVersion: v1
    kind: Namespace
    metadata:
      name: NAMESPACE
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: KSA_NAME
      namespace: NAMESPACE
    automountServiceAccountToken: false
    ---
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cloud-sdk-config
      namespace: NAMESPACE
    data:
      config: |
        {
          "type": "external_account",
          "audience": "identitynamespace:PROJECT_ID.svc.id.goog:IDENTITY_PROVIDER",
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/GSA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken",
          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
          "token_url": "https://sts.googleapis.com/v1/token",
          "credential_source": {
            "file": "/var/run/secrets/tokens/gcp-ksa/token"
          }
        }
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: cloud-sdk-example
      namespace: NAMESPACE
    spec:
      serviceAccount: KSA_NAME
      containers:
      - name: cloud-sdk
        image: gcr.io/google.com/cloudsdktool/cloud-sdk:latest
        command:
        - /bin/bash
        - -c
        - 'set -eu -o pipefail; while true; do gcloud compute zones list --filter="name ~ us-central1-*"; sleep 5; done'
        env:
        - name: CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
          value: /var/run/secrets/tokens/gcp-ksa/google-application-credentials.json
        - name: CLOUDSDK_CORE_PROJECT
          value: PROJECT_ID
        volumeMounts:
        - name: gcp-ksa
          mountPath: /var/run/secrets/tokens/gcp-ksa
          readOnly: true
      volumes:
      - name: gcp-ksa
        projected:
          defaultMode: 420
          sources:
          - serviceAccountToken:
              audience: PROJECT_ID.svc.id.goog
              expirationSeconds: 86400
              path: token
          - configMap:
              name: cloud-sdk-config
              optional: false
              items:
              - key: config
                path: google-application-credentials.json
    

    Replace the following:

    • PROJECT_ID
    • NAMESPACE
    • KSA_NAME
    • GSA_NAME
    • IDENTITY_PROVIDER with the name of the identity provider for your cluster.
  2. Apply the manifest to your cluster

    kubectl apply -f workload-identity-sample.yaml
    
  3. Verify the sample application is working, check the Pod's logs:

    kubectl logs -f cloud-sdk-example -n NAMESPACE
    

    Replace the following:

    • NAMESPACE

    If the Pod is successful in accessing the Google Cloud compute API, you will see output that looks similar to this:

    NAME           REGION       STATUS  NEXT_MAINTENANCE  TURNDOWN_DATE
    us-central1-c  us-central1  UP
    us-central1-a  us-central1  UP
    us-central1-f  us-central1  UP
    us-central1-b  us-central1  UP
    

Cleaning up

  1. Delete the sample application

    kubectl delete -f manifest.yaml
    
  2. Remove the IAM policy binding from the Google Cloud service account

    gcloud iam service-accounts remove-iam-policy-binding \
        GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --member serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE//KSA_NAME] \
        roles/iam.workloadIdentityUser
    

    Replace the following:

    • GSA_NAME
    • PROJECT_ID
    • NAMESPACE
    • KSA_NAME
  3. Remove the IAM policy binding from the project

    gcloud projects remove-iam-policy-binding PROJECT_ID \
        --member serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --role roles/compute.viewer
    

    Replace the following:

    • GSA_NAME
    • PROJECT_ID
  4. Delete the Google Cloud service account

    gcloud iam service-accounts delete \
       GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
    

    Replace the following:

    • GSA_NAME
    • PROJECT_ID

What's next