About service accounts in GKE

This page describes service accounts in Google Kubernetes Engine (GKE), which provide identities for applications.

Service accounts are identities that are intended for use by applications instead of people. In GKE, you interact with Kubernetes service accounts and with Identity and Access Management service accounts.

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.

  • To learn the basics of Kubernetes ServiceAccounts, in the Kubernetes documentation, see Service Accounts.
  • To learn how to create new ServiceAccounts, grant permissions using role-based access control (RBAC), and assign ServiceAccounts to Pods, see Configure Service Accounts for Pods.
  • For best practices when managing Kubernetes ServiceAccounts, see Best practices for RBAC.

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 disable the GKE service agent, you can recover it by following the instructions in Enabling a service account.

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.

If you delete the GKE service agent, you can undelete it by following the instructions in Undeleting a service account.

Default GKE node service account

By default, GKE nodes use the Compute Engine default service account. By default this service account is granted the Editor role (roles/editor) and has more permissions than what are required for GKE nodes. Consider using a role that uses the minimum permissions required to run nodes in the cluster.

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

Minimum permissions

GKE requires a minimum set of IAM permissions to operate your cluster. For instructions to create a minimally-privileged IAM service account, see Use least privilege Google 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, which has extensive permissions within your project.

What's next