Use Kubernetes service accounts

This page describes Kubernetes services accounts and how and when to use them in Google Kubernetes Engine (GKE).


Kubernetes service accounts are Kubernetes resources, created and managed using the Kubernetes API, meant to be used by in-cluster Kubernetes-created entities, such as Pods, to authenticate to the Kubernetes API server or external services.

Kubernetes service accounts are distinct from Identity and Access Management (IAM) service accounts.

When to use Kubernetes service accounts

Kubernetes service accounts let you give an identity to your Pods, which can be used to:

  • Authenticate Pods to the Kubernetes API server, allowing the Pods to read and manipulate Kubernetes API objects (for example, a CI/CD pipeline that deploys applications to your cluster).
  • Authenticate Pods to Google Cloud resources through Workload Identity, allowing Pods to act as an IAM service account. This allows you to give fine-grained identity and authorization to Pods when they need access to Google Cloud APIs.

Create a Kubernetes service account

To create a Kubernetes service account, perform the following tasks:

  1. Configure kubectl to communicate with your cluster:

    gcloud container clusters get-credentials CLUSTER_NAME

    Replace CLUSTER_NAME with the name of your cluster.

  2. Create a namespace:

    kubectl create namespace NAMESPACE_NAME

    Replace NAMESPACE_NAME with the name of your new namespace.

  3. Create the Kubernetes service account in the namespace:

    kubectl create serviceaccount KSA_NAME --namespace NAMESPACE_NAME

    Replace the following:

    • KSA_NAME: the name of your new Kubernetes service account.
    • NAMESPACE_NAME: the name of your namespace.

Assign a Kubernetes service account to a Pod

When using Kubernetes service accounts, you can choose between two different credential types:

  • Standard service account credentials: mounts a static long-lived credential for the service account into the Pod.

    apiVersion: v1
    kind: Pod
      name: POD_NAME
      namespace: NAMESPACE_NAME
      serviceAccountName: KSA_NAME
  • Service account token volume projection: Mounts a short-lived, automatically rotating Kubernetes service account token into the Pod. This token is a OpenID Connect Token and can be used to authenticate to the Kubernetes API and other external services.

    apiVersion: v1
    kind: Pod
      name: POD_NAME
      namespace: NAMESPACE_NAME
      - image: CONTAINER_NAME
        name: CONTAINER_NAME
        - mountPath: /var/run/secrets/tokens
          name: KSA_NAME_TOKEN
      serviceAccountName: KSA_NAME
      - name: KSA_NAME_TOKEN
          - serviceAccountToken:
              path: KSA_NAME_TOKEN
              expirationSeconds: 86400
              audience: some-oidc-audience

Best practices for managing service accounts

  • Separate service accounts by namespace according to your cluster's administrative boundaries. This allows you to restrict who can manage particular service accounts in your cluster, which might prove to be valuable as your organization grows.
  • Use one namespace per workload responsibility. However, if you have multiple workloads in a single namespace that require different responsibilities, use different service accounts for those workload responsibilities; do not use the default service account. If no service account is specified in a Pod, the Pod will run as the default service account in its namespace. By creating a Kubernetes service account for each workload, you are better able to enforce the principle of least privilege.
  • Use the service account token volume projection because this ensures service account credentials are short-lived, reducing the impact of leaked credentials.

Rotating Kubernetes service account credentials

If a Kubernetes service account credential is compromised and you wish to revoke the compromised credentials, take one of the following approaches:

  • Create a new Kubernetes service account, migrate the Pod and any authorization to the new service account, and then revoke access to the old Kubernetes service account.
  • Perform a credential rotation, which will revoke all the Kubernetes service account credentials in your cluster. The rotation also changes your cluster's CA certificate and IP address.

What's next