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:
kubectlto communicate with your cluster:
gcloud container clusters get-credentials CLUSTER_NAME
CLUSTER_NAMEwith the name of your cluster.
Create a namespace:
kubectl create namespace NAMESPACE_NAME
NAMESPACE_NAMEwith the name of your new namespace.
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 metadata: name: POD_NAME namespace: NAMESPACE_NAME spec: 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 metadata: name: POD_NAME namespace: NAMESPACE_NAME spec: containers: - image: CONTAINER_NAME name: CONTAINER_NAME volumeMounts: - mountPath: /var/run/secrets/tokens name: KSA_NAME_TOKEN serviceAccountName: KSA_NAME volumes: - name: KSA_NAME_TOKEN projected: sources: - 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.