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 user roles and tasks](https://docs.cloud.google.com/kubernetes-engine/enterprise/docs/concepts/roles-tasks.md.txt).

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

- [Identity and Access Management (IAM) allow policies](https://docs.cloud.google.com/iam/docs/policies)
- [How fleets work](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/fleet-concepts.md.txt)
- [Fleet team management](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/team-management.md.txt)
- [Kubernetes ServiceAccounts](https://kubernetes.io/docs/concepts/security/service-accounts/#authenticating-credentials)
- [Kubernetes projected volumes](https://kubernetes.io/docs/concepts/storage/projected-volumes/)

## 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](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/workload-identity.md.txt) 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 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](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/team-management.md.txt#fleet_team_management_overview),
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.

> [!WARNING]
>
> **Preview
> --- self-managed workload identity pools**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

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](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/about-fleet-workload-identity-federation.md.txt#supported-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](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/fleet-concepts.md.txt#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](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/team-management.md.txt#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)](https://docs.cloud.google.com/docs/authentication/application-default-credentials.md.txt)
   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](https://docs.cloud.google.com/docs/authentication/token-types.md.txt#fed-access-tokens) from [Security Token Service](https://docs.cloud.google.com/iam/docs/reference/sts/rest.md.txt) 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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects). - `PROJECT_ID`: your Fleet project ID. - `SERVICEACCOUNT_UID`: the UID of the `ServiceAccount` object in the API server. |

## What's next

- [Authenticate shared-trust fleet workloads to Google Cloud APIs](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/use-workload-identity.md.txt)
- [Authenticate mixed-trust fleet workloads to Google Cloud APIs](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/authenticate-mixed-trust-workloads.md.txt)
- [Best practices for using fleet Workload Identity Federation](https://docs.cloud.google.com/kubernetes-engine/fleet-management/docs/best-practices-workload-identity.md.txt)