Tutorial · AWS · Kubernetes identity
IRSA vs EKS Pod Identity
Apps on Kubernetes often need to use AWS — say, to read a file from S3. IRSA and Pod Identity are two ways to let an app prove who it is to AWS, safely and without stored passwords. This guide explains both from scratch, then shows the commands and how to fix the common errors.
01Fundamentals
Eight short lessons, in order. Each explains an idea in plain words, then shows a real example.
01 The problem: your app needs to get into AWS
Say you have an app running in a pod (how Kubernetes runs a program). It needs to read reports from an S3 bucket. AWS checks every request: "Who are you, and are you allowed to do this?" So the app needs to prove who it is. There are three ways:
Hard-coded keys
You paste an access key and secret into the app's settings.
Like taping your house key to the front door — it never expires, and anyone who sees it can use it.
The node's role
The app uses the IAM role attached to the server (the node) it runs on.
Like giving every tenant the master key — every app on that server gets the same access.
Per-app identity
Each app gets temporary credentials for its own role. Nothing secret is stored, and the pass expires on its own.
Like a visitor badge with your name that only opens your rooms and stops working tonight.
IRSA and Pod Identity are both ways to do the third option. The only difference is how the app gets its pass.
Show ID to AWS directly
The app shows its ID straight to AWS's security desk (STS). First you must tell AWS to recognize IDs from your cluster.
A helper fetches it
A helper on each server (the Pod Identity Agent) collects the pass from EKS for the app. EKS already knows your cluster, so there's less to set up.
02 OIDC: a standard way to vouch for someone
OIDC (OpenID Connect) is an agreed set of rules that lets one system say "I vouch for this identity" in a way another system can check — without sharing any passwords. The easiest picture is a passport: it carries an official seal that's hard to fake, it says who you are and when it expires, and a border officer can check it without phoning the issuing country.
On EKS: your cluster signs an ID token for the app (it's the issuer). The pod has the token saved as a file. The verifier checks the signature with the cluster's public key, and the app can then call S3.
Four words you'll keep seeing
Issuer — whoever creates and signs the token (your cluster). Token — the signed ID itself, a "JWT." Keys — the issuer signs with a secret private key; anyone checks with the matching public key. Verifier — whoever checks the token before letting you in (the border officer).
Where IRSA and Pod Identity differ: who checks the token. With IRSA, AWS STS checks it — but STS doesn't know your cluster, so you first register the cluster as a trusted issuer by creating an IAM OIDC provider (once per cluster). With Pod Identity, an EKS service checks it, and EKS already knows every cluster it runs — so there's nothing to register.
03 Signing: one secret key, one public key
How can AWS trust a token it never saw being made? A key pair: two keys made together. The private key only the issuer has — your cluster uses it to sign every token, and it never leaves the EKS control plane. The public key anyone can have — it can only check signatures, not create them, so it's safe to publish. If a signature checks out, two things are proven: the issuer really made the token, and not one character has changed since.
This uses your browser's real cryptography (RS256, the same family EKS uses), with a key pair generated on this page just now.
1 · the payload (edit it after signing)
signed token
s3-reader to admin and check again — the signature won't match, because only the private key could make a new one.Go deeper: how does AWS get your cluster's public key?
There's no secret handshake. EKS publishes each cluster's public keys at a public web address, and AWS STS downloads them when it needs to check a token:
- EKS makes the key pair when the cluster is created. The private key stays locked in the control plane.
- EKS publishes the public keys at the cluster's "issuer" address — a discovery document plus the key set (JWKS).
- You tell IAM to trust that address by creating the IAM OIDC provider. It stores the address, not the keys — so if EKS rotates keys, nothing on your side changes.
- A token arrives, STS fetches the keys using the token's
iss, picks the right key by itskid, and checks the signature.
ISSUER=$(aws eks describe-cluster --name demo \
--query "cluster.identity.oidc.issuer" --output text)
curl -s $ISSUER/.well-known/openid-configuration | jq '{issuer, jwks_uri}'
curl -s $(curl -s $ISSUER/.well-known/openid-configuration | jq -r .jwks_uri) | jq
# example output (shortened)
{ "keys": [ {
"kty": "RSA", # key type
"use": "sig", # used for signatures
"alg": "RS256", # signing method
"kid": "7a8c1f2e…", # key ID, matched against the token header
"n": "x9Fq…", "e": "AQAB" # the public key numbers
} ] }For Pod Identity, EKS checks the token with its own service (EKS Auth). EKS created the keys, so there's no address to register and nothing to download — which is why Pod Identity has no OIDC provider step.
04 Tokens: a postcard with a tamper-proof seal
The ID your pod carries is a JWT (JSON Web Token, said "jot"). Think of a postcard with a wax seal: anyone can read it, but nobody can change it without breaking the seal. It's three parts joined by dots:
- Header — how it was sealed and which key to check it with. Like the label on an envelope.
- Payload — the actual claims: who (
sub), for whom (aud), until when (exp). Like the message on the postcard. - Signature — made with the cluster's private key, checked with its public key. Like the wax seal.
Only the aud (audience) differs between an IRSA token and a Pod Identity token, because each is addressed to a different verifier.
Treat tokens like passwords
The example above is made up. Real tokens are private — treat them like a password while they're valid.
05 ServiceAccounts: name tags for apps
People log in with user accounts; apps use a ServiceAccount, which works like a name tag. Each pod wears exactly one (if you don't choose, it gets default). ServiceAccounts live in a namespace (like a department), so the full name includes it — the way you'd say "Jane from Finance." AWS sees it as system:serviceaccount:app:s3-reader.
apiVersion: v1
kind: Pod
metadata:
name: report-app
namespace: app # the department
spec:
serviceAccountName: s3-reader # the name tag (one line is all it takes)
containers:
- name: app
image: amazon/aws-cliTwo helpers you never see
A mutating webhook adds settings to the pod when it's created — where to find its token and credentials. Because this only happens at creation, restart the pod if you change roles later. The kubelet on each server writes a fresh, signed token to a file and replaces it before it expires, so your app never handles that.
06 IAM roles: a hat that gives you powers
An IAM role is like a work hat — whoever may put it on gets its powers, but only for a while. Roles have no password; you assume a role and get temporary credentials. Every role has two separate policies, and mixing them up is the most common beginner mistake:
The guest list
Who is allowed to put on the hat?
The key ring
Which doors does the hat open?
{ "Effect": "Allow",
"Principal": { "Service": "pods.eks.amazonaws.com" },
"Action": [ "sts:AssumeRole", "sts:TagSession" ] }{ "Effect": "Allow",
"Action": [ "s3:GetObject", "s3:ListBucket" ],
"Resource": [ "arn:aws:s3:::reports",
"arn:aws:s3:::reports/*" ] }Reading an AccessDenied
When you see AccessDenied, ask: did it fail at the guest list (the app couldn't get the role at all) or at the key ring (it got the role, but the role can't open that door)?
STS (Security Token Service) turns "I'm allowed to wear this hat" into actual temporary credentials — an access key, secret, session token and expiry (usually a few hours). The AWS SDK renews them automatically. Pod Identity also adds session tags (cluster, namespace, ServiceAccount, pod) automatically, so one role can safely serve many teams — each can only open things tagged with its own namespace. This is called ABAC (attribute-based access control).
07 How the SDK finds credentials: checking pockets in order
Your app's code usually doesn't mention credentials — it just says boto3.client("s3"). The AWS SDK then checks a fixed list of places in order, like checking your pockets one by one, and uses the first credentials it finds:
- Credentials hard-coded in the code or environment variables
- A shared credentials file (
~/.aws/credentials) - IRSA — the web-identity token file (
AWS_WEB_IDENTITY_TOKEN_FILE) - Pod Identity / ECS — the container credentials endpoint
- The EC2 instance (node) role, via IMDS
That's why IRSA and Pod Identity "just work" — and why a leftover setting in an earlier pocket can quietly win. (This is why, when switching from IRSA to Pod Identity, you must remove the IRSA annotation.)
08 Glossary
Plain-English definitions are collected at the bottom of this page.
02How it works, step by step
Pick a method and step through it. Each step lights up what's happening. Switch between the two to compare.
03Try the commands
Real commands, in the order you'd run them. Pick a method and a task. Placeholders: account 111122223333, cluster demo, region us-west-2, namespace app, ServiceAccount s3-reader.
04Differences, side by side
Short version: Pod Identity is simpler to set up and scales better, and AWS recommends it for most new apps on EKS. IRSA still matters where Pod Identity isn't available.
| Question | IRSA | EKS Pod Identity |
|---|---|---|
| Who checks the pod's ID? | AWS STS, after you register the cluster as an IAM OIDC provider | EKS itself. Nothing to register |
| Where you connect app → role | Two places: an annotation on the ServiceAccount and the role's guest list | One place: an association in EKS |
| Reuse the role in another cluster? | Edit the role's guest list for every new cluster | Just add an association. The role stays the same |
| Limits as you grow | 100 OIDC providers/account by default; a role's guest list fits only a handful of apps | None of these |
| Session tags (ABAC) | No | Yes, added automatically |
| Needs a helper on each server? | No — the pod talks to STS directly | Yes — the Pod Identity Agent (built in on Auto Mode) |
| Reaching another AWS account | Direct | Role chaining (built in, --target-role-arn) |
| Where it runs | EKS on EC2, Fargate & Windows, plus non-EKS Kubernetes | EKS Linux EC2 only. Not Fargate, Windows, Outposts, EKS Anywhere, self-managed |
| On EKS Auto Mode | Works | Recommended — the agent is already there |
Your apps run on normal EKS Linux servers or Auto Mode · you have (or will have) several clusters · you want one role to serve many teams safely with session tags.
Your pods run on Fargate or Windows · your Kubernetes isn't EKS (e.g. self-managed) · a tool you use only supports IRSA.
Switching from IRSA to Pod Identity
1) Add pods.eks.amazonaws.com to the role's guest list. 2) Create the association. 3) Remove the IRSA annotation from the ServiceAccount. 4) Restart the pods. Step 3 matters because the SDK checks the IRSA "pocket" first — if the annotation stays, the app keeps using IRSA.
05Fixing problems
Find the message you're seeing. The matching commands are under Try the commands → Fix problems.
| What you see | What it usually means | What to do |
|---|---|---|
App is using the node's role (from get-caller-identity) | The pod started before setup, or the name tag / namespace is misspelled. | Fix the names, then kubectl rollout restart. |
Not authorized to perform sts:AssumeRoleWithWebIdentity | IRSA: the role's guest list doesn't match the pod's token (usually a wrong namespace or SA name). | Read the token's sub and compare it with the trust policy, letter by letter. |
InvalidIdentityToken: No OpenIDConnect provider found | IRSA: AWS was never told to trust this cluster. | Create the IAM OIDC provider for the cluster. |
Read timeout … 169.254.170.23/v1/credentials | Pod Identity: the app can't reach the helper on its server. | Check the agent is running. Private clusters need an eks-auth VPC endpoint. Check proxy/firewall. |
not authorized … eks-auth:AssumeRoleForPodIdentity | Pod Identity: the server's own role can't ask EKS for credentials. | Attach AmazonEKSWorkerNodePolicy to the node role; check org SCPs. |
AccessDenied calling S3 (or another service) | The app got the right role, but the role's key ring doesn't open that door. | Fix the permission policy. CloudTrail shows exactly what was denied. |
Unable to locate credentials | The SDK found nothing in any pocket. It may be too old, or the app sets its own credentials. | Update the AWS SDK and let it use its default credential chain. |
Glossary
- pod
- The unit Kubernetes runs your app in — one or more containers together.
- ServiceAccount
- An identity ("name tag") a pod wears inside a namespace. AWS sees it as
system:serviceaccount:<namespace>:<name>. - namespace
- A Kubernetes "department" that groups resources; part of a ServiceAccount's full name.
- OIDC (OpenID Connect)
- A standard for one system to vouch for an identity so another can verify it, without sharing passwords.
- issuer
- Whoever creates and signs a token. On EKS, your cluster. Named in the token's
issclaim. - JWT
- JSON Web Token — a signed ID with three dot-separated parts: header, payload, signature.
- audience (
aud) - Who a token is addressed to. The only claim that differs between an IRSA and a Pod Identity token.
- subject (
sub) - Who the token is about — the ServiceAccount, in
system:serviceaccount:…form. - key pair
- A private key (signs, kept secret in the EKS control plane) and a matching public key (verifies, safe to publish).
- JWKS
- JSON Web Key Set — the public keys EKS publishes at the issuer address for verifiers to download.
kid- Key ID — names which public key signed a token, so keys can be rotated without breaking existing tokens.
- IAM OIDC provider
- A record in IAM that registers a cluster's issuer address as trusted. Needed for IRSA, once per cluster.
- IAM role
- A set of permissions with no password. You assume it to get temporary credentials.
- trust policy
- The role's "guest list" — who may assume it.
- permission policy
- The role's "key ring" — what it may do.
- STS
- AWS Security Token Service — issues the temporary credentials when a role is assumed.
- session tags / ABAC
- Attributes (cluster, namespace, SA, pod) Pod Identity attaches to a session, letting one role serve many teams via attribute-based access control.
- Pod Identity Agent
- A helper (DaemonSet) on each node that fetches credentials from EKS for pods.