Vault Kubernetes Auth: Service Account Login
Kubernetes auth lets a pod log in to Vault with its service account token, no static secret needed.
When CI runs inside Kubernetes (self-hosted runners on a cluster, for instance), the pod already holds a projected service account JWT. Vault verifies it with the cluster and issues a token.
What it does
Vault Kubernetes auth validates a pod service account JWT against the Kubernetes TokenReview API. A role binds the allowed service account names and namespaces and attaches policies. The pod logs in by writing its JWT to auth/kubernetes/login with a role.
Common usage
# Vault config (run once)
vault auth enable kubernetes
vault write auth/kubernetes/config \
kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443"
vault write auth/kubernetes/role/ci \
bound_service_account_names="ci-runner" \
bound_service_account_namespaces="ci" \
token_policies="ci" ttl=20m
# login from inside the pod
JWT=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
vault write -field=token auth/kubernetes/login role=ci jwt="$JWT"Options
| Field | What it does |
|---|---|
| bound_service_account_names | Service accounts allowed to use the role |
| bound_service_account_namespaces | Namespaces allowed to use the role |
| kubernetes_host | API server URL Vault uses for TokenReview |
| token_policies | Policies attached to issued tokens |
In CI
On clusters issuing audience-bound projected tokens, the service account token must carry an audience Vault accepts; set audience on the role or use a projected volume with the right audience. This avoids storing any Vault credential in the runner image.
Common errors in CI
"permission denied" on login often means the Vault server service account lacks the system:auth-delegator ClusterRole needed to call TokenReview. "invalid role name 'ci'" means the role does not exist or is in another namespace/mount. "service account name not authorized" means the pod service account is not in bound_service_account_names. An audience mismatch shows as "invalid audience".