CloudConsole

EKS IRSA: IAM role trust policy for a service account

Updated 17 November 2026 · How we write and check guides

Short answer

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.

Policy diagram: 1 statement(s); first Allow sts:AssumeRoleWithWebIdentity on * (all resources)
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

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 puts system:serviceaccount:<namespace>:<service-account> in projected service account tokens. Matching it exactly means only pods using the payments-api service account in the payments namespace 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-api

Restart 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-api

It 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/token

If these variables are missing, the webhook didn't mutate the pod: check the annotation and restart it.

Common mistakes

  • StringLike with system: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 this happens away from your desk

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

Sources