A pod identity association lets the pods of one Kubernetes service account act as a bot. Pods get short-lived API keys for the bot, made when they ask for them. Nothing is stored in the cluster, and no key is written into a Secret.
Create an association
ezgh kubernetes pod-identity-associations create --cluster kcl_3k9d0a1m2x7q \
--namespace shop --service-account checkout --bot bot_5t7y9u1i3oqaCreating or changing an association needs bots.pass on its bot. Associations change at once
(CreatePodIdentityAssociation); a namespace and
service account have one association per cluster.
Pods created after the association exists get two environment variables:
| Variable | |
|---|---|
EZGH_CONTAINER_CREDENTIALS_FULL_URI |
Where the pod asks for keys. |
EZGH_CONTAINER_AUTHORIZATION_TOKEN_FILE |
The pod’s service account token, which it presents when it asks. |
Restart the pods of a service account that existed before its association.
The pod-identity-agent add-on answers those requests. It’s installed in every cluster; removing it
stops pod identity.
Keys
Each key acts as the bot and lasts 1 hour. Every key is made for the request that asked for it, after checking that the pod still exists and that the association still names its bot, so deleting an association stops new keys at once.
What a pod does shows in Trails as the bot, with the credential Kubernetes pod API key
and the service account (shop/checkout) it came from.
Clients that read the variables
The ezgh CLI reads them, from version 0.52.1: in a pod with an association, ezgh commands run as
the bot with no sign-in.
A client that doesn’t read the variables can ask for a key itself: GET the URL in
EZGH_CONTAINER_CREDENTIALS_FULL_URI with the contents of the token file in the Authorization header.
Read the file on every request: Kubernetes rotates the token.
{
"apiKey": "…",
"expiresAt": "2026-11-07T09:30:00.000Z",
"bot": "…"
}Use apiKey as a bearer credential (Authorization: Bearer …) until expiresAt, and fetch a new one
before then. A 429 or 503 answer carries Retry-After.
Instance metadata
Pods can’t reach the instance metadata service, so they never get the node’s own bot. A pod with
hostNetwork: true can.
The cluster’s OIDC issuer
Each cluster publishes its service account issuer as an OIDC discovery document at its oidcIssuer
(https://kubernetes-api.ezghcloud.com/oidc/kcl_3k9d0a1m2x7q). Any OIDC relying party can trust the
cluster’s service account tokens, including an OIDC provider in your organization.