ServiceAccount

ServiceAccount
Name	ServiceAccount
Type	Kubernetes resource
Introduced	2014
Platform	Kubernetes, OpenShift
Related	ServiceAccountToken, RoleBinding, ClusterRoleBinding, Secret

ServiceAccount

A ServiceAccount provides an identity for processes that run in pods on container orchestration platforms such as Kubernetes and OpenShift Container Platform. It lets system components and workloads obtain credentials to access APIs and resources, integrating with controllers like kube-controller-manager and schedulers such as kube-scheduler. Implementations interact with cluster components including etcd, kube-apiserver, and authentication modules like OpenID Connect providers and ServiceAccountTokenProjection.

Overview

ServiceAccount is a namespaced resource originally designed for automated non-human identities in Kubernetes clusters managed by projects like Cloud Native Computing Foundation. It appears alongside other core objects such as Pod, Secret, ConfigMap, Deployment, DaemonSet, and StatefulSet. The runtime lifecycle is tied to controllers and kubelets which mount tokens into pods or project tokens via mechanisms pioneered by Kubernetes SIG Auth. ServiceAccount objects are stored in etcd and validated by admission controllers such as NodeRestriction and PodSecurityPolicy replacements.

Purpose and Use Cases

ServiceAccount provides an API identity for in-cluster components and third-party operators like Prometheus Operator, Istio, Cert-Manager, Argo CD, and Flux. It is used by system services including kube-proxy and control plane add-ons, as well as CI/CD runners such as Jenkins agents and Tekton tasks. Use cases include granting read-only access for observability tools to query kube-apiserver, enabling controllers to reconcile resources via CustomResourceDefinition controllers, and allowing mesh sidecars managed by Envoy to authenticate with control planes.

Creation and Configuration

ServiceAccount objects can be created declaratively via manifests applied with tools like kubectl, helm, kustomize, and oc; imperatively they can be created with API calls to kube-apiserver or SDKs such as client libraries for Go, Python, and Java. A typical manifest includes metadata with annotations for integrations like Istio Sidecar Injector or Kubernetes Admission Controllers. ServiceAccount may reference or be associated with Secrets such as token Secrets or image pull Secrets used by registries like Harbor, Docker Hub, or Quay. Namespaces such as kube-system, default, and user-created project namespaces scope ServiceAccount objects.

Authentication and Tokens

ServiceAccount tokens historically relied on long-lived Secrets containing bearer tokens mounted into pods; this model was used by components including kubelet and kube-apiserver integrations. Modern clusters favor bound ServiceAccount tokens issued by the API server via the TokenRequest API, leveraging features like audience, expiration, and bounded lifetimes similar to tokens from OpenID Connect providers including Dex and Keycloak. Token projection techniques allow pods to receive tokens without writing Secrets to disk, integrating with mechanisms used by SPIFFE and Vault for workload identity. Token validation occurs at kube-apiserver and can be combined with Webhook Token Authentication.

Permissions and Role Binding

ServiceAccount itself is only an identity; permissions are granted through Role, ClusterRole, RoleBinding, and ClusterRoleBinding resources administered by controllers such as kube-controller-manager. RoleBindings tie ServiceAccounts to roles that permit API actions on resources like Pods, Secrets, ConfigMaps, and CRDs defined by operators such as Prometheus Operator or ArgoCD Operator. Best practice patterns appear in hardening guides from projects like CNCF and distributions such as Red Hat OpenShift and Google Kubernetes Engine, emphasizing least privilege via namespaced Roles and judicious use of ClusterRoleBindings.

Best Practices and Security Considerations

Apply least privilege by granting minimal Roles consistent with recommendations from CIS Kubernetes Benchmark and vendors like Aqua Security and Sysdig. Prefer short-lived, audience-bound tokens via TokenRequest and use projected ServiceAccount tokens instead of auto-mounted Secrets to reduce disk exposure. Avoid using default ServiceAccount in namespaces where elevated access is unnecessary; use distinct ServiceAccounts for controllers, operators, and CI/CD agents. Combine RoleBinding auditing with tools like Open Policy Agent and admission controls such as Gatekeeper to enforce policy. Rotate credentials and monitor for anomalous token usage with logging backends like ELK Stack or Prometheus and alerting via Alertmanager.

Troubleshooting and Common Issues

Common issues include pods failing to mount tokens due to kubelet misconfiguration, RoleBinding scoping errors causing forbidden API responses, and expiration or audience mismatches when using TokenRequest-based tokens with external systems like Istio or Vault. Diagnosis steps use commands and tools such as kubectl describe pod, kubectl get serviceaccount, kubectl get rolebinding, controller logs from kube-controller-manager, and API server audit logs. Other frequent problems arise from misconfigured imagePullSecrets referencing registries like Docker Hub or Quay, or from cluster admission controllers rejecting ServiceAccount-related changes; resolving these often involves inspecting admission webhook logs and reviewing cluster RBAC policies per guidelines from Kubernetes Documentation and security advisories from vendors such as Google Cloud or Red Hat.

Category:Kubernetes