About service accounts in GKE

This page describes service accounts in Google Kubernetes Engine (GKE) and how they provide identities for applications. You'll learn about the different types of service accounts and when to use each type to authenticate access to resources within GKE without relying on personal credentials.

This page is for Security specialists and Operators who create and manage service accounts to interact with GKE applications. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE Enterprise user roles and tasks.

Kubernetes service accounts and IAM service accounts

The following table describes the main differences between Kubernetes service accounts and IAM service accounts:

Types of service accounts in GKE
Kubernetes ServiceAccount
  • ServiceAccount object in the Kubernetes API server
  • Scoped to a Kubernetes namespace in a cluster
  • Provides an identity for Pods to use inside the cluster
IAM service account
  • Manage using the IAM API
  • Scoped to a Google Cloud project
  • Provides an identity for applications in the project

Kubernetes ServiceAccounts

Kubernetes service accounts are managed at the cluster level and exist in the Kubernetes API server as ServiceAccount objects. The Kubernetes documentation and the GKE documentation often use the term ServiceAccount to distinguish these Kubernetes resources from service accounts in other environments like IAM.

You create a Kubernetes ServiceAccount in a namespace and then assign that ServiceAccount to a Pod by using the serviceAccountName field in the Pod manifest. The kubelet process on the node gets a short-lived bearer token for the assigned ServiceAccount and mounts the token as a projected volume in the Pod.

The short-lived bearer token is a JSON web token (JWT) that's signed by the API server, which is an OpenID Connect (OIDC) provider. To validate the bearer token, get the public validation key for the cluster by calling the projects.locations.clusters.getJwks method in the GKE API.

Rotating Kubernetes ServiceAccount credentials

If a Kubernetes service account credential is compromised, use one of the following options to revoke the credentials:

  • Recreate your Pods: The bearer token is bound to each unique Pod UID, so recreating the Pods invalidates the previous credentials.
  • Recreate the Kubernetes service account: The bearer token is bound to the UID of the ServiceAccount object in the Kubernetes API. Delete the ServiceAccount and create a new ServiceAccount with the same name. Previous tokens become invalid because the UID of the new ServiceAccount is different.
  • Perform a credential rotation: This operation revokes all the Kubernetes service account credentials in your cluster. The rotation also changes your cluster's CA certificate and IP address. For details, see credential rotation.

IAM service accounts

IAM service accounts are managed at the project level using the IAM API. You can use these service accounts to perform actions like programmatically calling Google Cloud APIs and managing permissions for applications running in Google Cloud products.

To learn more, see the IAM service accounts overview.

GKE service agents

A IAM service agent is an IAM service account that Google Cloud manages.

GKE uses the Kubernetes Engine Service Agent to manage the lifecycle of cluster resources on your behalf such as nodes, disks, and load balancers. This service agent has the domain container-engine-robot.iam.gserviceaccount.com and is granted the Kubernetes Engine Service Agent role (roles/container.serviceAgent) on your project when you enable the GKE API.

The identifier of this service agent is as follows:

service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com

PROJECT_NUMBER is your numerical project number.

If you remove the service agent's permissions in your project, you can recover them by following the instructions in Error 400/403: Missing edit permissions on account.

Default GKE node service account

GKE uses IAM service accounts that are attached to your nodes to run system tasks like logging and monitoring. At a minimum, these node service accounts must have the Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) role on your project. By default, GKE uses the Compute Engine default service account, which is automatically created in your project, as the node service account.

If your organization enforces the iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint, the default Compute Engine service account in your project might not automatically get the required permissions for GKE.

If you use the Compute Engine default service account for other functions in your project or organization, the service account might have more permissions than GKE needs, which could expose you to security risks.

To grant the roles/container.defaultNodeServiceAccount role to the Compute Engine default service account, complete the following steps:

console

  1. Go to the Welcome page:

    Go to Welcome

  2. In the Project number field, click Copy to clipboard.
  3. Go to the IAM page:

    Go to IAM

  4. Click Grant access.
  5. In the New principals field, specify the following value: 
    PROJECT_NUMBER-compute@developer.gserviceaccount.com
     Replace PROJECT_NUMBER with the project number that you copied.
  6. In the Select a role menu, select the Kubernetes Engine Default Node Service Account role.
  7. Click Save.

gcloud

  1. Find your Google Cloud project number: 
    gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"

    Replace PROJECT_ID with your project ID.

    The output is similar to the following:

    12345678901
  2. Grant the roles/container.defaultNodeServiceAccount role to the Compute Engine default service account: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/container.defaultNodeServiceAccount"

    Replace PROJECT_NUMBER with the project number from the previous step.

Don't disable the default Compute Engine service account unless you are migrating to user-managed service accounts.

When to use a specific service account

The type of service account that you use depends on the type of identity that you want to provide for your applications, as follows:

  • Provide an identity for your Pods to use in the cluster: Use a Kubernetes ServiceAccount. Every Kubernetes namespace has a default ServiceAccount, but we recommend that you create new minimally-privileged ServiceAccounts for each workload in each namespace.
  • Provide an identity for your Pods to use outside the cluster: Use Workload Identity Federation for GKE. Workload Identity Federation for GKE lets you specify Kubernetes resources like ServiceAccounts as principals in IAM policies. For example, use Workload Identity Federation for GKE when calling Google Cloud APIs like Secret Manager or Spanner from your Pods.
  • Provide a default identity for your nodes: Use a custom minimally-privileged IAM service account when you create your GKE clusters or nodes. If you don't use a custom IAM service account, GKE uses the Compute Engine default service account.

What's next