Fleet workload identity

Applications often need to authenticate (provide an authenticatable identity) when connecting to other services. For example, your applications must authenticate to use Google Cloud APIs such as the Compute Engine or AI Platform APIs. This page explains how to use fleet workload identity, the recommended and simplest way for application workloads hosted in a fleet to authenticate to Google Cloud APIs and services. You can find out more about fleets and how they help you manage your infrastructure and applications in Introducing fleets.

What is fleet workload identity?

Fleets use workload identity federation to provide each application with a distinct federated identity that can be used to authenticate to Google Cloud and other services you develop. Applications running in a fleet receive a federated workload identity in the following format:

serviceAccount:FLEET_PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]

Where:

  • FLEET_PROJECT_ID.svc.id.goog is a short-form representation of the workload identity pool for your fleet. There is only one fixed workload identity pool per fleet and it is automatically created for you.
  • K8S_NAMESPACE is the Kubernetes namespace where the Kubernetes service account is defined.
  • KSA_NAME is the name of the Kubernetes service account attached to the application.

All applications hosted in a fleet share the same workload identity pool, providing applications with a federated identity that abstracts away where each application is hosted. This makes it possible to give an application within a fleet access to a resource (such as a Google Cloud API) just once rather than cluster-by-cluster, even if the application is deployed across Google Cloud projects or across different clouds. Like other fleet-enabled features, this relies on the fleet principle of sameness, where Kubernetes objects with the same name in different clusters are treated as the same thing. So, for example, if you have an application with a backend deployed across multiple clusters in the same fleet, and which needs to authenticate to a Google API, you can easily configure your application so that all services in the "backend" namespace can access that API. You can read much more about how fleets use sameness, including identity sameness, in Introducing fleets.

Clusters outside Google Cloud can also use fleet Workload Identity to provide an identity for the Connect Agent to authenticate to Google. You can find out more about this in Registering a cluster.

Before you start

  • Ensure that you have the following command line tools installed:

    • The latest version of the Cloud SDK, which includes gcloud, the command line tool for interacting with Google Cloud.
    • kubectl

    If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.

  • Ensure that you have initialized the gcloud tool for use with your project.

Cluster setup

Before applications in your fleet can receive a workload identity, the clusters that they run on must be registered to your fleet and properly configured to use fleet Workload Identity. How you do this depends on the type of cluster. Most Anthos clusters outside Google Cloud are registered automatically to your project fleet when you create them. GKE clusters on Google Cloud and attached clusters must be registered manually.

See the documentation for each cluster type for more information about cluster configuration.

GKE

  1. Enable GKE Workload Identity on your Google Kubernetes Engine cluster, if it is not already enabled.
  2. Follow the instructions to register the cluster using Workload Identity.

Anthos clusters outside Google Cloud

Anthos clusters on VMware, Anthos clusters on bare metal, and Anthos clusters on AWS are automatically registered to your project fleet at cluster creation time. As of Anthos 1.8, all these cluster types automatically enable fleet Workload Identity when registered. Existing registered clusters are updated to use Workload Identity when they are upgraded to Anthos 1.8.

Anthos clusters on Azure currently must be manually registered following the instructions in Register your cluster with Connect. These instructions enable fleet Workload Identity by default.

Attached clusters

Attached clusters can be registered with fleet Workload Identity enabled if they meet the necessary requirements. Follow the instructions for your cluster type in Registering a cluster.

Using fleet workload identity

After you have registered your cluster, workloads deployed on the cluster can use workload identities from the fleet workload identity pool. This section shows you how to use the workload identity to impersonate a Google Cloud service account so your workloads can access Google Cloud APIs. Acting as a service account is a common use case for federated identities, as it lets your workloads authenticate to any Google Cloud API that the service account has access to, removing the maintenance and security burden of having to manage service account keys for each workload.

Impersonate a service account

This section shows how to configure an application's federated workload identity to impersonate a service account by providing an application default credentials file in a ConfigMap, including creating and configuring the service account with the relevant permissions.

The example uses the following placeholder values:

  • WORKLOAD_IDENTITY_POOL is the workload identity pool associated with your fleet. As shown above, the value of WORKLOAD_IDENTITY_POOL is FLEET_PROJECT_ID.svc.id.goog.
  • IDENTITY_PROVIDER is the name of the identity provider associated with your Kubernetes cluster.
  • K8S_NAMESPACE is the Kubernetes namespace where the Kubernetes service account is defined.
  • KSA_NAME is the name of the Kubernetes service account attached to the application.
  • GSA_NAME is the name of the Google service account your application will act as.
  • GSA_PROJECT_ID is the project ID where the Google service account is defined.

To configure a fleet workload identity to impersonate a service account:

  1. Ensure your cluster is registered to the fleet by following the steps in the Cluster setup section above.

  2. Get the values of WORKLOAD_IDENTITY_POOL and IDENTITY_PROVIDER for your registered cluster by retrieving the cluster's fleet membership details, using the following command. Replace MEMBERSHIP with your cluster's unique membership name in the fleet:

    gcloud container hub memberships describe MEMBERSHIP
    

    The output of describing the membership looks like this (some fields have been omitted for clarity):

    authority:
     identityProvider: IDENTITY_PROVIDER
     workloadIdentityPool: WORKLOAD_IDENTITY_POOL
    name: projects/FLEET_PROJECT_ID/locations/global/memberships/MEMBERSHIP
    
  3. Create a Google Cloud service account that your application can impersonate when authenticating to Google, if you don't have one already:

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

    The service account doesn't need to be in your fleet host project. You can use any Google Cloud service account in your organization. You can find out more about service accounts and how they work in Service accounts.

  4. Ensure that you've granted the service account any permissions it needs to access Google Cloud APIs by adding the necessary IAM policy bindings. You can do this by using gcloud iam service-accounts add-iam-policy-binding, or another method if preferred. You can find out which permissions are required to use Google Cloud APIs in each service's documentation, and see a complete list of predefined roles with the necessary permissions in Understanding roles.

  5. Authorize your application's workload identity to impersonate the service account by creating an IAM policy binding, as follows. This binding allows your application's federated workload identity to act as the Google Cloud service account.

    gcloud iam service-accounts add-iam-policy-binding \
      GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/iam.workloadIdentityUser \
      --member="serviceAccount:WORKLOAD_IDENTITY_POOL[K8S_NAMESPACE/KSA_NAME]"
    

    The --member field is IAM's representation of your application's federated workload identity.

  6. Create a ConfigMap that contains the application default credentials file for your workload. This file tells the client library compiled into your workload how to authenticate to Google. The application default credentials file contains the relevant workload identity pool and service account information, as well as the path to the projected token that will be mounted in your container's filesystem in the next step. GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com is the email address of the service account to impersonate.

    This configuration by itself does not grant access to impersonate the service account. If the IAM binding does not exist as well, the Pod will not be able to use the service account.

    kind: ConfigMap
    apiVersion: v1
    metadata:
      namespace: K8S_NAMESPACE
      name: my-cloudsdk-config
    data:
      config: |
        {
          "type": "external_account",
          "audience": "identitynamespace:WORKLOAD_IDENTITY_POOL:IDENTITY_PROVIDER",
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/GSA_NAME@GSA_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"
          }
        }
    
  7. Follow the example below to configure your workload. Note the ConfigMap from the previous step is mounted in the container's filesystem as google-application-credentials.json, alongside a projected service account token file, in /var/run/secrets/tokens/gcp-ksa. Projected tokens are issued by Kubernetes and represent the workload's identity inside the cluster. These tokens are automatically exchanged with Google by Cloud Client Libraries to obtain tokens that can authenticate with Google APIs. The audience field of the projected token must be set to the value of WORKLOAD_IDENTITY_POOL.

    kind: Namespace
    apiVersion: v1
    metadata:
      name:  K8S_NAMESPACE
    ---
    kind: ServiceAccount
    apiVersion: v1
    metadata:
      namespace:  K8S_NAMESPACE
      name: KSA_NAME
    automountServiceAccountToken: false
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: my-pod
      namespace:  K8S_NAMESPACE
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: my-image
        env:
          - name: GOOGLE_APPLICATION_CREDENTIALS
            value: /var/run/secrets/tokens/gcp-ksa/google-application-credentials.json
        volumeMounts:
        - name: gcp-ksa
          mountPath: /var/run/secrets/tokens/gcp-ksa
          readOnly: true
      volumes:
      - name: gcp-ksa
        projected:
          defaultMode: 420
          sources:
          - serviceAccountToken:
              path: token
              audience: WORKLOAD_IDENTITY_POOL
              expirationSeconds: 172800
          - configMap:
              name: my-cloudsdk-config
              optional: false
              items:
                - key: "config"
                  path: "google-application-credentials.json"
    
    

Authenticate from your code

Cloud Client Libraries automatically handle authenticating to Google Cloud when you use them to access Google services from your code. In order to use the setup shown above in your applications, you must use Cloud Client Libraries that support Workload Identity Federation. The following shows the minimum required Cloud Client Libraries versions, as well as instructions for how to check your current version:

C++

Most of the Google Cloud Client Libraries for C++ support identity federation by using a ChannelCredentials object, which is created by calling grpc::GoogleDefaultCredentials(). To initialize this credential, you must build the client libraries with version 1.36.0 or later of gRPC.

The Cloud Storage Client Library for C++ uses the REST API, not gRPC, so it does not support identity federation.

Go

Client libraries for Go support identity federation if they use version v0.0.0-20210218202405-ba52d332ba99 or later of the golang.org/x/oauth2 module.

To check which version of this module your client library uses, run the following commands:

cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2

Java

Client libraries for Java support identity federation if they use version 0.24.0 or later of the com.google.auth:google-auth-library-oauth2-http artifact.

To check which version of this artifact your client library uses, run the following Maven command in your application directory:

mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

Node.js

Client libraries for Node.js support identity federation if they use version 7.0.2 or later of the google-auth-library package.

To check which version of this package your client library uses, run the following command in your application directory:

npm list google-auth-library

When you create a GoogleAuth object, you can specify a project ID, or you can allow GoogleAuth to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the README for the google-auth-library package.

Python

Client libraries for Python support identity federation if they use version 1.27.0 or later of the google-auth package.

To check which version of this package your client library uses, run the following command in the environment where the package is installed:

pip show google-auth

To specify a project ID for the authentication client, you can set the GOOGLE_CLOUD_PROJECT environment variable, or you can allow the client to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the user guide for the google-auth package.