eks-irsa

用途

EKS IRSA 技能用于在 Amazon EKS 中配置 Pod 级别的 AWS 权限。IRSA（IAM Roles for Service Accounts）通过 OpenID Connect（OIDC）联邦，使 Kubernetes 工作负载能够安全地承担 IAM 角色，而无需依赖节点级 IAM 凭据，从而实现最小权限安全。

适用场景包括：

在 EKS 中设置 Pod 级 AWS 权限
配置 AWS 服务集成（S3、DynamoDB、Secrets Manager、SQS、SNS）
安装 EKS 附加组件（AWS Load Balancer Controller、EBS CSI Driver、External DNS）
实施最小权限安全架构
排查 OIDC 信任关系问题
从 EKS 跨账户承担 IAM 角色
从节点 IAM 角色迁移到 Pod 级权限
使用 IRSA 进行蓝绿集群升级

主要能力

IRSA 的工作流程：

Pod 以带注解的 ServiceAccount 启动
EKS 变更 Webhook 注入 AWS_WEB_IDENTITY_TOKEN_FILE
AWS SDK 从注入文件读取 JWT 令牌
SDK 调用 STS::AssumeRoleWithWebIdentity
OIDC 提供商根据信任策略验证令牌
颁发临时凭据（自动轮换）
Pod 使用限定范围的 IAM 权限

主要优势：

安全：Pod 级权限（非节点级）、防止权限提升、自动凭据轮换、无长期凭据
合规：最小权限原则、通过 CloudTrail 审计追踪、满足合规要求、细粒度访问控制
运维：每个应用拥有独立 IAM 角色、无需更改节点即可修改权限、更好的资源隔离、支持多租户

使用方式

前置条件：

已启用 OIDC 提供商（使用 terraform-aws-modules/eks 时自动启用）
已创建带 OIDC 信任策略的 IAM 角色
ServiceAccount 已注解角色 ARN
Pod 已配置使用该 ServiceAccount

Terraform 快速设置示例：

# 1. 在 EKS 模块中启用 IRSA（自动设置 OIDC）
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name = "production"
  enable_irsa  = true  # 自动创建 OIDC 提供商
}

# 2. 为 S3 访问创建 IAM 角色
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. 创建 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. 在 Pod 中使用 ServiceAccount
resource "kubernetes_deployment" "my_app" {
  spec {
    template {
      spec {
        service_account_name = "my-app-sa"  # ✅ 已启用 IRSA！

        containers {
          name  = "app"
          image = "my-app:latest"
          # AWS SDK 自动使用 IRSA 凭据
        }
      }
    }
  }
}

验证 IRSA 设置：

# 检查 OIDC 提供商是否存在
aws iam list-open-id-connect-providers

# 验证 IAM 角色信任策略
aws iam get-role --role-name my-app-s3-access

# 从 Pod 内测试
kubectl exec -it my-pod -- env | grep AWS
# 应显示：
# 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

# 测试 AWS 访问
kubectl exec -it my-pod -- aws s3 ls

eksctl 快速设置：

# 创建启用 OIDC 的集群
eksctl create cluster \
  --name production \
  --region us-east-1 \
  --with-oidc

# 一条命令创建 IRSA 角色 + ServiceAccount
eksctl create iamserviceaccount \
  --name my-app-sa \
  --namespace production \
  --cluster production \
  --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
  --approve

# 验证
kubectl get sa my-app-sa -n production -o yaml

常见 IRSA 模式

技能文档提供了以下集成模式的 Terraform 示例：

AWS Load Balancer Controller：创建/管理 ALB 和 NLB
EBS CSI Driver：创建/挂载/删除 EBS 卷
External DNS：管理 Route53 记录
Cluster Autoscaler：修改 Auto Scaling Groups
Karpenter（推荐自动扩缩器）：配置 EC2 实例、管理实例配置文件
External Secrets Operator：从 AWS Secrets Manager 读取密钥
自定义应用（S3 + DynamoDB）：使用最小权限自定义策略

应用代码示例

AWS SDK 会自动检测 IRSA 凭据，无需额外配置。文档提供了 Python（Boto3）、Node.js（AWS SDK v3）和 Go（AWS SDK v2）的示例代码。

安全最佳实践

使用专用 ServiceAccount：每个应用一个 ServiceAccount，避免共享
限制 IMDS 访问：要求 IMDSv2（http_tokens = "required"），防止容器逃逸到节点凭据
最小权限策略：使用精确的 Action 和 Resource，并可通过 Condition 限制
定期审计：查找所有 IRSA 角色，检查 CloudTrail 中的 AssumeRoleWithWebIdentity 调用

故障排查

常见问题与修复：

AccessDenied：缺少 IAM 权限，检查角色策略是否允许该操作
AssumeRoleWithWebIdentity failed：信任策略不匹配，验证 OIDC 提供商 ARN 与集群匹配
InvalidIdentityToken：信任中的命名空间/SA 错误，检查 StringEquals 条件
Pod 无法承担角色：ServiceAccount 未注解，添加 eks.amazonaws.com/role-arn 注解
使用节点凭据：Pod 未使用 ServiceAccount，在 Pod 规范中设置 serviceAccountName
找不到 OIDC 提供商：未启用 IRSA，在 EKS 模块中设置 enable_irsa = true

蓝绿集群升级

问题：IRSA 信任策略包含集群 OIDC 端点。解决方案：升级期间更新信任策略，临时同时支持蓝绿两个集群的 OIDC 提供商 ARN。

限制与替代方案

EKS Pod Identity 是 IRSA 的新简化替代方案（2024 年 GA）：

无需 OIDC 提供商
更简单的信任策略
完全由 AWS 管理
推荐用于新部署

IRSA 与 Pod Identity 对比：

IRSA：成熟、广泛使用（2019 年起）
Pod Identity：更简单、更新、AWS 管理（2024 年起）

迁移路径：现有集群保留 IRSA，新集群使用 Pod Identity。

详细文档

技能包含以下参考文档：

references/oidc-setup.md：OIDC 提供商配置、信任关系剖析、指纹计算、蓝绿集群升级
references/role-creation.md：常见服务的 IAM 角色模式、自定义策略示例、ABAC 会话标签、跨账户访问
references/pod-configuration.md：ServiceAccount 注解、Pod 规范、环境变量、故障排查

版本：2025 最佳实践 Terraform 模块：terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks 状态：生产就绪最后更新：2025 年 11 月