adaptationio/eks-irsa

EKS IAM Roles for Service Accounts (IRSA)

Overview

Comprehensive guide for implementing IAM Roles for Service Accounts (IRSA) in Amazon EKS. IRSA enables fine-grained IAM permissions at the pod level using OpenID Connect (OIDC) federation, eliminating the need for node-level IAM credentials and enabling least-privilege security.

Keywords: IRSA, IAM Roles for Service Accounts, EKS security, OIDC provider, pod IAM permissions, service account annotations, least privilege, AWS integration, trust policy, cross-account access

Status: Production-ready (2025 best practices)

When to Use This Skill

• Setting up pod-level AWS permissions in EKS
• Configuring AWS service integrations (S3, DynamoDB, Secrets Manager, SQS, SNS)
• Installing EKS add-ons (AWS Load Balancer Controller, EBS CSI Driver, External DNS)
• Implementing least-privilege security architecture
• Troubleshooting OIDC trust relationship issues
• Cross-account IAM role assumption from EKS
• Migrating from node IAM roles to pod-level permissions
• Blue/green cluster upgrades with IRSA

What is IRSA?

IAM Roles for Service Accounts (IRSA) allows Kubernetes workloads to assume IAM roles securely without relying on node-level credentials.

How IRSA Works

1. Pod starts with annotated ServiceAccount
2. EKS mutating webhook injects AWS_WEB_IDENTITY_TOKEN_FILE
3. AWS SDK reads JWT token from injected file
4. SDK calls STS::AssumeRoleWithWebIdentity
5. OIDC provider validates token against trust policy
6. Temporary credentials issued (automatically rotated)
7. Pod uses scoped IAM permissions

Key Benefits

Security:

• Pod-level permissions (not node-level)
• Prevents privilege escalation
• Automatic credential rotation
• No long-lived credentials

Compliance:

• Least-privilege principle
• Audit trail via CloudTrail
• Compliance requirements met
• Fine-grained access control

Operational:

• Each app gets own IAM role
• Modify permissions without node changes
• Better resource isolation
• Supports multi-tenancy

Quick Start

Prerequisites

1. OIDC Provider Enabled (automatic with terraform-aws-modules/eks)
2. IAM Role Created with trust policy for OIDC
3. ServiceAccount Annotated with role ARN
4. Pod Configured to use ServiceAccount

30-Second Setup (Terraform)

# 1. Enable IRSA in EKS module (automatic OIDC setup)
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name = "production"
  enable_irsa  = true  # Creates OIDC provider automatically
}

# 2. Create IAM role for S3 access
module "s3_access_irsa" {
  source  = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
  version = "~> 5.0"

  role_name = "my-app-s3-access"

  role_policy_arns = {
    s3_read = "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
  }

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["production:my-app-sa"]
    }
  }
}

# 3. Create Kubernetes ServiceAccount
resource "kubernetes_service_account" "my_app" {
  metadata {
    name      = "my-app-sa"
    namespace = "production"
    annotations = {
      "eks.amazonaws.com/role-arn" = module.s3_access_irsa.iam_role_arn
    }
  }
}

# 4. Use ServiceAccount in pod
resource "kubernetes_deployment" "my_app" {
  spec {
    template {
      spec {
        service_account_name = "my-app-sa"  # ✅ IRSA enabled!

        containers {
          name  = "app"
          image = "my-app:latest"
          # AWS SDK automatically uses IRSA credentials
        }
      }
    }
  }
}

Verify IRSA Setup

# Check OIDC provider exists
aws iam list-open-id-connect-providers

# Verify IAM role trust policy
aws iam get-role --role-name my-app-s3-access

# Test from pod
kubectl exec -it my-pod -- env | grep AWS
# Should show:
# AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
# AWS_ROLE_ARN=arn:aws:iam::123456789012:role/my-app-s3-access

# Test AWS access
kubectl exec -it my-pod -- aws s3 ls

Common IRSA Patterns

1. AWS Load Balancer Controller

What it needs: Create/manage ALBs and NLBs

module "lb_controller_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name                              = "aws-load-balancer-controller"
  attach_load_balancer_controller_policy = true  # Pre-built policy!

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["kube-system:aws-load-balancer-controller"]
    }
  }
}

2. EBS CSI Driver

What it needs: Create/attach/delete EBS volumes

module "ebs_csi_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name             = "ebs-csi-controller"
  attach_ebs_csi_policy = true  # Pre-built policy!

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["kube-system:ebs-csi-controller-sa"]
    }
  }
}

3. External DNS

What it needs: Manage Route53 records

module "external_dns_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name                     = "external-dns"
  attach_external_dns_policy    = true  # Pre-built policy!
  external_dns_hosted_zone_arns = ["arn:aws:route53:::hostedzone/Z123456789"]

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["kube-system:external-dns"]
    }
  }
}

4. Cluster Autoscaler

What it needs: Modify Auto Scaling Groups

module "cluster_autoscaler_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name                        = "cluster-autoscaler"
  attach_cluster_autoscaler_policy = true  # Pre-built policy!
  cluster_autoscaler_cluster_names = [module.eks.cluster_name]

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["kube-system:cluster-autoscaler"]
    }
  }
}

5. Karpenter (Recommended Autoscaler)

What it needs: Provision EC2 instances, manage instance profiles

module "karpenter" {
  source = "terraform-aws-modules/eks/aws//modules/karpenter"

  cluster_name           = module.eks.cluster_name
  irsa_oidc_provider_arn = module.eks.oidc_provider_arn

  # Includes pre-configured IRSA role!
}

6. External Secrets Operator

What it needs: Read secrets from AWS Secrets Manager

module "external_secrets_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name                      = "external-secrets"
  attach_external_secrets_policy = true  # Pre-built policy!

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["kube-system:external-secrets"]
    }
  }
}

7. Custom Application (S3 + DynamoDB)

module "app_irsa" {
  source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"

  role_name = "my-app"

  role_policy_arns = {
    s3       = aws_iam_policy.app_s3_policy.arn
    dynamodb = aws_iam_policy.app_dynamodb_policy.arn
  }

  oidc_providers = {
    main = {
      provider_arn               = module.eks.oidc_provider_arn
      namespace_service_accounts = ["production:my-app-sa"]
    }
  }
}

# Custom policies with least privilege
resource "aws_iam_policy" "app_s3_policy" {
  name = "my-app-s3-access"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "s3:GetObject",
          "s3:PutObject"
        ]
        Resource = "arn:aws:s3:::my-bucket/my-app/*"
      }
    ]
  })
}

Application Code Examples

Python (Boto3)

import boto3

# AWS SDK automatically detects IRSA credentials
# No configuration needed!

s3 = boto3.client('s3')
response = s3.list_buckets()
print(response['Buckets'])

# The SDK:
# 1. Reads AWS_WEB_IDENTITY_TOKEN_FILE env var
# 2. Reads AWS_ROLE_ARN env var
# 3. Calls STS::AssumeRoleWithWebIdentity
# 4. Uses temporary credentials automatically

Node.js (AWS SDK v3)

import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";

// AWS SDK automatically detects IRSA credentials
const s3Client = new S3Client({ region: "us-east-1" });

const response = await s3Client.send(new ListBucketsCommand({}));
console.log(response.Buckets);

Go (AWS SDK v2)

import (
    "context"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    // AWS SDK automatically detects IRSA credentials
    cfg, _ := config.LoadDefaultConfig(context.TODO())
    client := s3.NewFromConfig(cfg)

    resp, _ := client.ListBuckets(context.TODO(), &s3.ListBucketsInput{})
    fmt.Println(resp.Buckets)
}

Detailed Documentation

For in-depth guides on specific IRSA topics:

• OIDC Setup: references/oidc-setup.md

  • OIDC provider configuration
  • Trust relationship anatomy
  • Thumbprint calculation
  • Blue/green cluster upgrades

• Role Creation: references/role-creation.md

  • IAM role patterns for common services
  • Custom policy examples
  • Session tags for ABAC
  • Cross-account access

• Pod Configuration: references/pod-configuration.md

  • ServiceAccount annotations
  • Pod specifications
  • Environment variables
  • Troubleshooting

Security Best Practices

1. Use Dedicated Service Accounts

# ❌ BAD: Sharing service account
apiVersion: v1
kind: ServiceAccount
metadata:
  name: shared-sa  # Used by multiple apps
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123:role/shared-role

# ✅ GOOD: One service account per app
apiVersion: v1
kind: ServiceAccount
metadata:
  name: payment-service-sa
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123:role/payment-service
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: email-service-sa
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123:role/email-service

2. Restrict IMDS Access

# Prevent pods from accessing node IAM credentials
module "eks" {
  source = "terraform-aws-modules/eks/aws"

  eks_managed_node_groups = {
    main = {
      # Require IMDSv2 (prevents container escape to node credentials)
      metadata_options = {
        http_endpoint               = "enabled"
        http_tokens                 = "required"  # IMDSv2 only
        http_put_response_hop_limit = 1
      }
    }
  }
}

3. Least Privilege Policies

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::my-bucket/my-app/*",
      "Condition": {
        "StringEquals": {
          "aws:PrincipalAccount": "123456789012"
        }
      }
    }
  ]
}

4. Regular Auditing

# Find all IRSA roles
aws iam list-roles --query 'Roles[?contains(AssumeRolePolicyDocument.Statement[0].Principal.Federated, `oidc-provider`)]'

# Check CloudTrail for AssumeRoleWithWebIdentity calls
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRoleWithWebIdentity \
  --max-results 50

Troubleshooting Quick Reference

| Issue | Cause | Fix | |-------|-------|-----| | AccessDenied | Missing IAM permissions | Check role policy allows action | | AssumeRoleWithWebIdentity failed | Trust policy mismatch | Verify OIDC provider ARN matches cluster | | InvalidIdentityToken | Wrong namespace/SA in trust | Check StringEquals condition | | Pod can't assume role | ServiceAccount not annotated | Add eks.amazonaws.com/role-arn annotation | | Using node credentials | Pod not using ServiceAccount | Set serviceAccountName in pod spec | | OIDC provider not found | IRSA not enabled | Set enable_irsa = true in EKS module |

eksctl Quick Setup

# Create cluster with OIDC enabled
eksctl create cluster \
  --name production \
  --region us-east-1 \
  --with-oidc

# Create IRSA role + ServiceAccount in one command
eksctl create iamserviceaccount \
  --name my-app-sa \
  --namespace production \
  --cluster production \
  --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
  --approve

# Verify
kubectl get sa my-app-sa -n production -o yaml

Blue/Green Cluster Upgrades

Problem: IRSA trust policies include cluster OIDC endpoint

Solution: Update trust policies during upgrade

# Support both blue and green clusters temporarily
resource "aws_iam_role" "app" {
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = [
            module.eks_blue.oidc_provider_arn,   # Old cluster
            module.eks_green.oidc_provider_arn   # New cluster
          ]
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "${module.eks_blue.oidc_provider}:sub"  = "system:serviceaccount:prod:app-sa"
            "${module.eks_green.oidc_provider}:sub" = "system:serviceaccount:prod:app-sa"
          }
        }
      }
    ]
  })
}

EKS Pod Identity (New Alternative)

Note: EKS Pod Identity is the new simplified alternative to IRSA (GA 2024).

Differences:

• No OIDC provider needed
• Simpler trust policies
• Managed by AWS entirely
• Recommended for new deployments

IRSA vs Pod Identity:

• IRSA: Proven, mature, widely used (2019+)
• Pod Identity: Simpler, newer, AWS-managed (2024+)
• Both work, Pod Identity is easier for new clusters

Migration Path: Keep IRSA for existing clusters, use Pod Identity for new ones.

---

Version: 2025 Best Practices Terraform Module: terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks Status: Production-ready Last Updated: November 2025