EKS IRSA: IAM role trust policy for a service account
The role trusts your cluster's OIDC provider with sts:AssumeRoleWithWebIdentity, and the conditions pin it to one Kubernetes service account: sub equals system:serviceaccount:<namespace>:<name> and aud equals sts.amazonaws.com. Then annotate the service account with the role ARN.
The trust policy
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PaymentsApiServiceAccount",
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:payments:payments-api",
"oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
}
}
}
]
}Replace the issuer ID with your cluster's, and attach the role's permissions (for example DynamoDB or S3) as normal policies.
What the conditions do
- Federated principal: tokens must be issued by this cluster's OIDC issuer, registered as an IAM identity provider in your account.
:sub: Kubernetes putssystem:serviceaccount:<namespace>:<service-account>in projected service account tokens. Matching it exactly means only pods using thepayments-apiservice account in thepaymentsnamespace get the role.:aud: the audience the EKS pod identity webhook requests.
Set it up
aws eks describe-cluster --name my-cluster \
--query cluster.identity.oidc.issuer --output text
aws iam create-open-id-connect-provider \
--url https://oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE \
--client-id-list sts.amazonaws.com
aws iam create-role --role-name payments-api \
--assume-role-policy-document file://irsa-trust.json
kubectl annotate serviceaccount -n payments payments-api \
eks.amazonaws.com/role-arn=arn:aws:iam::123456789012:role/payments-apiRestart the pods after annotating; the webhook only injects the token and environment variables when a pod is created.
The newer alternative: EKS Pod Identity
EKS Pod Identity avoids per-cluster OIDC providers. The role trusts one service principal, and the mapping to a service account lives in EKS:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EksPodIdentity",
"Effect": "Allow",
"Principal": {
"Service": "pods.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}aws eks create-pod-identity-association --cluster-name my-cluster \
--namespace payments --service-account payments-api \
--role-arn arn:aws:iam::123456789012:role/payments-apiIt needs the EKS Pod Identity Agent add-on on the cluster. Because the trust policy no longer names a cluster, the same role can be reused across clusters; scope it with session-tag conditions if that matters.
Check from inside the pod
kubectl exec -n payments deploy/payments-api -- env | grep AWS_
# AWS_ROLE_ARN=arn:aws:iam::123456789012:role/payments-api
# AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/tokenIf these variables are missing, the webhook didn't mutate the pod: check the annotation and restart it.
Common mistakes
StringLikewithsystem:serviceaccount:*: every service account in every namespace can assume the role.- Typo in the issuer ID, or the provider registered in another account: errors say not authorized to perform
sts:AssumeRoleWithWebIdentity. - Pods still using the node role: the service account wasn't annotated before the pod started, or the pod spec uses a different service account.
- Blocking IMDS on nodes is still worth doing, so pods can't fall back to the node's instance role.
Questions
What is the sub claim for an EKS service account?
system:serviceaccount:<namespace>:<service-account-name>, for example system:serviceaccount:payments:payments-api.
Should I use IRSA or EKS Pod Identity?
Pod Identity is simpler for new clusters: no OIDC provider per cluster and one trust policy shape. IRSA works everywhere, including clusters not on EKS-managed infrastructure that Pod Identity doesn't support.
When a pod starts getting AccessDenied, the first check is which role it actually assumed. The CloudTrail AssumeRoleWithWebIdentity event shows that, and you can read it from a phone.
About the app → · Download on the App Store