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 |
|
IAM service account |
|
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.
- 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.
- To read the OIDC configuration of the Kubernetes API server for a cluster,
call the
projects.locations.clusters.well-known.getOpenid-configuration
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 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
- Learn how to use minimally privileged Google service accounts.
- Learn how to grant a role to a principal.