About fleet Workload Identity Federation

This page describes fleet Workload Identity Federation, which is a mechanism for authenticating requests from fleet workloads to Google Cloud APIs. On this page, you learn about identity sameness for workloads, how fleet Workload Identity Federation works, and good practices for managing it at scale.

This page is for Platform admins and operators and for Security engineers who want to more efficiently manage workload authorization at scale. To learn more about the user roles and example tasks that we reference in Google Cloud documentation, see Common GKE Enterprise user roles and tasks.

Before reading this page, ensure that you're familiar with the following concepts:

About federated workload identities in Google Cloud

Workload Identity Federation is a Google Cloud feature that lets the workloads in your clusters authenticate to Google Cloud without requiring you to download, manually rotate, and generally manage credentials. Instead, workloads authenticate using short-lived tokens generated by Google Cloud.

Workload Identity Federation for GKE is a GKE-specific implementation of Workload Identity Federation that provides a project-wide Google-managed workload identity pool from which applications running in GKE clusters get identities. Fleet Workload Identity Federation extends Workload Identity Federation for GKE to all fleet member clusters, regardless of whether the clusters are in different projects or are outside of Google Cloud. With fleet Workload Identity Federation, registered clusters that have Workload Identity Federation enabled on their fleet membership get identities using a fleet-wide Google-managed workload identity pool. This shared pool lets you configure authentication to Google Cloud APIs and to other services across your entire fleet, even across multiple projects.

Fleet Workload Identity Federation can also be used by the Connect Agent on some cluster types to authenticate to Google Cloud as part of fleet membership, and is required to use some GKE Enterprise features that work across projects, such as Cloud Service Mesh.

About workload identity pools

A workload identity pool is an entity that centrally manages identities for your applications. When you enable Workload Identity Federation for GKE on your clusters, the cluster project gets a Google-managed workload identity pool that has a fixed, project-specific name. Applications in your clusters get identities from the Google-managed workload identity pool to authenticate Google Cloud API calls. The Google-managed workload identity pool has the syntax PROJECT_ID.svc.id.goog, where PROJECT_ID is the cluster project ID.

With fleet Workload Identity Federation, the Google-managed workload identity pool of the fleet host project is also the workload identity pool for all clusters that you register to the fleet, regardless of whether those clusters are in other projects or are outside of Google Cloud. Every cluster in the fleet uses the FLEET_HOST_PROJECT_ID.svc.id.goog workload identity pool, where FLEET_HOST_PROJECT_ID is the project ID of the fleet host project.

If you use team scopes, you can optionally configure a self-managed IAM workload identity pool for clusters to use in addition to the Google-managed pool. This self-managed pool provides more explicit control over which workloads get specific identities.

Each application in your fleet gets a distinct federated identity from the fleet's workload identity pool that the application can use to authenticate to Google Cloud and to other services that you develop. Applications get a principal identifier that IAM can recognize. This identifier uses the following syntax:

PREFIX://iam.googleapis.com/projects/FLEET_PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_IDENTITY_POOL_NAME/SELECTOR

This syntax has the following fields:

  • PREFIX: principal or principalSet, depending on the type of Kubernetes resource that you select in the SELECTOR field.
  • FLEET_PROJECT_NUMBER: the project number of the fleet host project.

  • WORKLOAD_IDENTITY_POOL_NAME: the workload identity pool for your fleet. This value depends on the workload identity pool that you set up in each cluster, as follows:

    • Google-managed workload identity pool: FLEET_HOST_PROJECT_ID.svc.id.goog

    • Self-managed workload identity pool (Preview): POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog, where POOL_HOST_PROJECT_NUMBER is the project number of the project that you created the self-managed workload identity pool in.

  • SELECTOR: the resource selector. For a list of supported selectors, see the supported principal identifiers section. For example, subject/ns/NAMESPACE/sa/SERVICEACCOUNT selects a specific Kubernetes ServiceAccount in a specific namespace.

The entire fleet shares a fleet workload identity pool so that you can give applications anywhere in the fleet, including in other projects or clouds, access to the same resources without needing to manage that access for each cluster.

About identity sameness

Like other fleet-enabled features, fleet Workload Identity Federation relies on the principle of sameness, in which Kubernetes objects that have the same name and namespace in different clusters are treated as the same thing. To learn more about the general principle of sameness in fleets, see Sameness.

With single-project Workload Identity Federation for GKE, identity sameness applies to all entities that share a principal identifier in that project. However, with fleet Workload Identity Federation, this identity sameness implicitly applies to all entities that share a principal identifier across the entire fleet, regardless of the cluster project.

For example, consider an application with a backend that's deployed across multiple clusters in the same fleet. If you grant a role to a principal identifier that selects the default Kubernetes ServiceAccount in the backend Kubernetes namespace, any application in that namespace that uses that ServiceAccount gets the same access.

If your fleet only runs clusters in the fleet host project, the identity sameness implications are the same as for Workload Identity Federation for GKE. However, if your fleet has clusters that run in other projects or outside of Google Cloud, this implicit identity sameness extends to all of the registered clusters in the fleet.

Identity sameness in multi-tenant or mixed-trust environments

By default, your fleet uses the Google-managed workload identity pool of the fleet host project to provide identities to workloads across the fleet. All of the clusters in the fleet host project, including standalone clusters that aren't registered to the fleet, use this workload identity pool. In a mixed-trust environment where these standalone clusters run workloads that have a different trust model, this implicit identity sameness might result in unintended access.

Fleets let you manage this multi-tenant model by using team scopes and fleet namespaces. Team scopes let you designate subsets of fleet resources, like clusters, for use by specific teams in your organization. Fleet namespaces let you define Kubernetes namespaces within specific team scopes, so that certain teams can only run workloads in the namespaces in their team scope. For details, see Fleet team management overview.

If you use team scopes, you can mitigate identity sameness complexities in multi-tenant fleets by configuring your own workload identity pool for specific clusters in your fleet to use instead of the Google-managed workload identity pool. As a result, the principal identifiers for those workloads are explicitly different from the principal identifiers for standalone clusters in the project. This explicit identity sameness provides administrators with more control over the boundaries within which identity sameness applies.

The identity sameness model in your fleet changes as follows, based on whether you use only the Google-managed workload identity pool or configure a self-managed workload identity pool:

  • Implicit identity sameness: all of the workloads in a fleet use the Google-managed workload identity pool. As a result, every workload that shares the same principal identifier implicitly shares the same access.

  • Explicit identity sameness (Preview): you configure a self-managed workload identity pool for team scopes in the fleet. The self-managed pool only provides identities to workloads if you configure a cluster to use the self-managed pool for a specific fleet namespace. Workloads that run in other Kubernetes namespaces and clusters can't use the self-managed pool.

    As a result, the identity sameness of workloads that use the self-managed pool is different from the identity sameness of workloads that can only use the Google-managed workload identity pool.

When to use self-managed workload identity pools

Use the Google-managed workload identity pool if every cluster has a similar level of trust in which the same entities deploy the same applications. For example, a team-specific fleet with a cluster in each region that deploys a replicated application in each cluster.

We recommend that you configure a self-managed workload identity pool for your fleet in scenarios like the following:

  • Multiple trust levels in the fleet: you run clusters that have multiple trust levels. For example, consider a scenario in which finance teams and frontend teams have clusters in the same fleet. A self-managed workload identity pool helps you to separate the access grants for each team by fleet namespace. This means that even the cluster administrator of the frontend cluster can't get an identity in the fleet namespace unless they have explicit permissions.
  • Multiple trust levels in the project: your fleet host project runs standalone clusters that might not have the same trust level as your fleet clusters. By default, these standalone clusters use the Google-managed workload identity pool of the fleet host project. Your fleet clusters also use this workload identity pool, regardless of the fleet cluster project. Setting a self-managed workload identity pool for the fleet ensures that access grants on the self-managed pool don't unintentionally grant access to the standalone clusters.
  • Best practices for team scopes: you already use fleet team management features and want to implement recommended best practices for granting access to workloads. Setting a self-managed workload identity pool lets you grant access to workloads in a specific fleet namespace in a team scope without granting that access to other team scopes that run workloads in the same clusters.

How fleet Workload Identity Federation works

The following sections describe how fleet Workload Identity Federation works, including the flow of authentication credentials and supported IAM principal identifiers.

Credential flow

To let applications in a specific namespace authenticate using fleet Workload Identity Federation, you do the following:

  1. Deploy a ConfigMap in that namespace that has the following information:

    • The workload identity pool and the identity provider for your cluster.
    • The path in each Pod onto which Kubernetes mounts a ServiceAccount token. This token is a signed JSON Web Token (JWT).

    This ConfigMap functions as the application default credentials (ADC) file for workloads.

  2. Create an IAM allow policy that grants access on specific Google Cloud resources to the principal identifier of the principal in your clusters, like a ServiceAccount in the namespace.

  3. Ensure that your workload in the namespace has the following configurations in the Pod specification:

    • The GOOGLE_APPLICATION_CREDENTIALS environment variable set to the mount path of the ConfigMap in the Pod.
    • A projected volume that contains the ServiceAccount token and the ConfigMap that you created, mounted in the same path that you specify in the GOOGLE_APPLICATION_CREDENTIALS environment variable.
    • A volume mount in the container that references the projected volume.

When the workload makes a Google Cloud API call, the following steps happen:

  1. The Google Cloud authentication libraries use Application Default Credentials (ADC) to find credentials. ADC checks the path that you specified in the GOOGLE_APPLICATION_CREDENTIALS environment variable to look for an authentication token.
  2. The ADC authentication library uses the data in the ConfigMap to exchange the ServiceAccount JWT that you mounted on the Pod for a short-lived federated access token from Security Token Service that references the principal identifier of the workload.
  3. ADC includes the federated access token with the API request.
  4. The IAM allow policy authorizes the principal identifier to perform the requested operation on the Google Cloud resource.

Supported principal identifiers for fleet Workload Identity Federation

The following table describes the selectors that you can use in IAM allow policies to reference principals in fleets:

Principal identifier type Syntax
All Pods that use a specific Kubernetes ServiceAccount Select the ServiceAccount by name: 
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/SERVICEACCOUNT

Replace the following:

  • PROJECT_NUMBER: your numerical project number. To get the project number, see Identifying projects.
  • PROJECT_ID: your Google Cloud project ID.
  • NAMESPACE: the Kubernetes namespace.
  • SERVICEACCOUNT: the Kubernetes ServiceAccount name.
Select the ServiceAccount by UID: 
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.serviceaccount.uid/SERVICEACCOUNT_UID

Replace the following:

  • PROJECT_NUMBER: your numerical project number. To get the project number, see Identifying projects.
  • PROJECT_ID: your Fleet project ID.
  • SERVICEACCOUNT_UID: the UID of the ServiceAccount object in the API server.

What's next