---
title: "Pod identity"
description: "Let a service account's pods call EZGH APIs as a bot, with short-lived keys and nothing stored in the cluster."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pod identity

A pod identity association lets the pods of one Kubernetes service account act as a [bot](/iam/bots).
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

```sh
ezgh kubernetes pod-identity-associations create --cluster kcl_3k9d0a1m2x7q \
  --namespace shop --service-account checkout --bot bot_5t7y9u1i3oqa
```

Creating or changing an association needs `bots.pass` on its bot. Associations change at once
([CreatePodIdentityAssociation](/kubernetes-api/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](/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.

```json
{
  "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](/iam/kubernetes) in your organization.

Source: https://docs.ezghcloud.com/kubernetes/pod-identity/index.mdx
