IAM Roles for Service Accounts (IRSA) in EKS: Secure Pod Access to AWS

Simple explanation

When a pod in EKS needs to call an AWS API, it needs credentials. IRSA provides those credentials automatically and securely, scoped to just that workload.

The way it works: an IAM role is associated with a Kubernetes service account. When a pod starts using that service account, the AWS SDK inside the pod detects and uses temporary credentials tied to that role. The credentials expire after a short period and refresh automatically. Nobody needs to create, store, or rotate static access keys.

The IAM role is not attached directly to the pod. It is attached to the Kubernetes service account, and the pod inherits it by referencing that service account. A pod that does not specify the annotated service account receives no IRSA credentials.

In one sentence: IRSA lets a Kubernetes pod call AWS APIs using temporary, scoped IAM credentials, with no static keys anywhere in the chain.

Why IRSA exists

When pods need to call AWS services, there are a few ways to provide credentials, and they have very different security outcomes.

Node IAM roles: Every EC2 node in an Amazon EKS cluster runs with an IAM instance profile. Any pod on that node can reach the instance metadata endpoint and use those permissions. If you grant the node permission to read an S3 bucket so one pod can access it, every pod on that node gets the same access across every namespace. Applying the principle of least privilege at the pod level is not possible this way.

IRSA: Associate a Kubernetes service account with an IAM role. Only pods that explicitly use that service account can assume the role. The credentials are short-lived tokens, automatically rotated, and scoped to exactly the permissions in that role. This is the recommended approach for production workloads.

How IRSA works

IRSA uses OpenID Connect (OIDC) federation between your EKS cluster and AWS IAM. Here is the flow step by step:

1. OIDC provider enabled. Your EKS cluster is associated with an OIDC identity provider. This is a one-time per-cluster setup that tells AWS IAM to trust tokens the cluster issues.
2. IAM role with a scoped trust policy. You create an IAM role whose trust policy allows the EKS OIDC provider to assume it, but only when the token belongs to a specific service account in a specific namespace.
3. Service account annotated. The Kubernetes service account is annotated with the IAM role ARN. This is the link between the Kubernetes identity and the AWS identity.
4. Pod uses that service account. The pod spec references the annotated service account. A mutating webhook automatically injects a projected token file path and two environment variables (AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE) into the pod.
5. SDK exchanges the token. The AWS SDK reads those environment variables, loads the projected JWT, and calls sts:AssumeRoleWithWebIdentity. AWS validates the token against the OIDC provider and returns temporary credentials.
6. Credentials refresh automatically. The pod gets short-lived credentials that expire in hours. The SDK refreshes them before they expire, without any intervention needed.

The trust chain is: EKS issues a signed token, IAM trusts that OIDC issuer, STS validates the token and returns temporary credentials. No permanent keys exist anywhere in this flow.

How to set up IRSA with eksctl

The fastest path is to use eksctl, which handles the IAM role, trust policy, and service account annotation in a single command.

Step 1: Enable the OIDC provider for your cluster

This associates your cluster with an OIDC provider in IAM. Run this once per cluster before creating any IRSA resources.

eksctl utils associate-iam-oidc-provider \
  --cluster my-cluster \
  --region eu-west-1 \
  --approve

Step 2: Create the IAM service account

This creates the IAM role, writes a scoped trust policy, and creates the annotated Kubernetes service account, all in one step.

eksctl create iamserviceaccount \
  --name my-app-sa \
  --namespace production \
  --cluster my-cluster \
  --region eu-west-1 \
  --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
  --approve

Step 3: Reference the service account in your Deployment

Set serviceAccountName in the pod spec. Without this, the pod uses the default service account and receives no IRSA credentials.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      serviceAccountName: my-app-sa
      containers:
      - name: my-app
        image: my-app:1.0.0

The AWS SDK in your application detects and uses the injected credentials automatically. No code changes are needed.

Manual setup: trust policy and service account annotation

If you manage the IAM role yourself through Terraform, CloudFormation, or the AWS CLI, here is what you need to configure.

IAM trust policy

Replace the OIDC provider URL and account ID with your own values. The OIDC provider URL is available in the EKS cluster details in the AWS console or via aws eks describe-cluster.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.eu-west-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.eu-west-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:production:my-app-sa",
          "oidc.eks.eu-west-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

Two conditions matter here:

• sub (subject): scopes the role to one specific service account in one namespace. The format is system:serviceaccount:<namespace>:<service-account-name>. Without this condition, any service account in the cluster could assume the role.
• aud (audience): restricts which STS endpoint can be used. This should always be sts.amazonaws.com.

Kubernetes service account with the role ARN annotation

After creating the IAM role, create the service account and add the eks.amazonaws.com/role-arn annotation. This annotation is the bridge between the Kubernetes identity and the IAM role.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app-sa
  namespace: production
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-app-irsa-role

How to verify IRSA is working

Exec into the running pod and check which identity STS returns:

kubectl exec -it deploy/my-app -n production -- aws sts get-caller-identity

The output should show the IAM role ARN you created, not the EC2 node’s instance profile ARN. If the instance profile appears, something in the setup is misconfigured.

Troubleshooting checklist:

• Pod is using the right service account. Run kubectl get pod <pod-name> -n production -o jsonpath='{.spec.serviceAccountName}'. It should return my-app-sa, not default.
• Service account has the annotation. Run kubectl get sa my-app-sa -n production -o yaml and confirm eks.amazonaws.com/role-arn is present.
• OIDC provider is enabled. Run aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer". If the result is empty, the OIDC provider has not been associated with the cluster.
• Trust policy matches exactly. The sub condition is an exact string match against system:serviceaccount:production:my-app-sa. A typo in either the namespace or service account name silently breaks the credential exchange.

When to use IRSA

IRSA is appropriate any time a pod needs to call an AWS API and you want access scoped to that specific workload. Common scenarios:

• A pod reads objects from a specific S3 bucket. The IAM role allows s3:GetObject on that bucket only.
• An application fetches one secret from Secrets Manager at startup. The role allows secretsmanager:GetSecretValue on that one secret ARN. See Managing Secrets in Kubernetes on AWS for how IRSA integrates with the External Secrets Operator.
• A workload writes records to a single DynamoDB table. The role is scoped to dynamodb:PutItem on that table.
• Different teams run separate workloads in the same cluster and each needs different AWS permissions. Each team gets its own service account and IAM role with no credential sharing between them.

IRSA is especially useful in multi-tenant clusters where workload isolation matters. Each service account maps to a distinct IAM role, so you enforce permission boundaries through IAM rather than relying solely on Kubernetes RBAC. See Securing EKS Clusters for how IRSA fits into a broader cluster security posture.

IRSA vs node IAM roles vs EKS Pod Identity

There are three main ways to give pods access to AWS services. Understanding the differences helps you pick the right approach.

Node IAM roles assign permissions to the EC2 instance rather than to individual pods. All pods on a node share the same permissions. This is simple to set up but violates least privilege. You cannot scope access to one pod without granting the same access to every pod on that node.

IRSA ties an IAM role to a Kubernetes service account via OIDC federation. Pods using the annotated service account receive temporary STS credentials scoped to that role. Setup requires associating an OIDC provider with the cluster, writing a scoped trust policy, and annotating the service account. IRSA is stable, widely supported, and works with all recent AWS SDK versions.

EKS Pod Identity (introduced in 2023) removes the need to configure a per-cluster OIDC provider. The EKS Pod Identity Agent, a DaemonSet running on each node, intercepts credential requests from pods and returns temporary credentials via the EKS Auth service. You associate an IAM role with a service account using a single EKS API call. EKS Pod Identity simplifies setup on new clusters, but IRSA is not obsolete. It remains the right choice for clusters already using OIDC or environments where the Pod Identity agent is unavailable.

For a deeper look at how AssumeRoleWithWebIdentity and the STS trust model work, see AWS Role Assumption Explained.