eksctl 实战:使用 IAM Roles for Service Accounts(IRSA)为 EKS 应用绑定细粒度 AWS 权限

原创2026-10-14 09:39:501,820 阅读
文章标签:云原生容器编排DevOps

eksctl 实战:使用 IAM Roles for Service Accounts(IRSA)为 EKS 应用绑定细粒度 AWS 权限

导读

本文基于 eksctl 官方文档中关于 IAM Roles for Service Accounts(IRSA)的完整指南,结合仓库源码深入讲解如何在 Amazon EKS 集群中,用 eksctl 将 AWS IAM Role 与 Kubernetes Service Account 一一绑定,为运行在集群里的应用提供访问 S3、DynamoDB、RDS、ElastiCache 等 AWS 服务的细粒度权限。读完本文,你将掌握:IRSA 的底层工作原理(IAM OIDC Provider + Webhook 注入)、eksctl create/update/delete iamserviceaccount 系列命令的全部关键参数(含 --role-only、--role-name、--attach-role-arn、--subject-pattern 等进阶用法)、以及通过 ClusterConfig 配置文件批量管理 iamserviceaccount 的完整姿势。

💡 提示:eksctl 还提供了更新的细粒度权限方案 —— EKS Pod Identity Associations,它可以不依赖 OIDC Provider、让一个 IAM Role 跨多个集群复用。本文仍以 IRSA 为主,但会在文末说明两者关系与选择建议。

什么是 IAM Roles for Service Accounts(IRSA)

Amazon EKS 原生支持 IRSA(IAM Roles for Service Accounts):集群管理员可以将一个 AWS IAM Role 映射到某个 Kubernetes Service Account,从而让使用该 Service Account 的 Pod 获得访问其他 AWS 服务(S3、RDS、MQ、STS、DynamoDB 等)的临时凭证。

典型的适用对象包括业务应用,以及运行在集群内的 AWS 生态组件,例如 AWS Load Balancer Controller、ExternalDNS 等。在 eksctl 中,这类资源被命名为 iamserviceaccount,它代表「一个 IAM Role + 一个 Kubernetes Service Account」的成对组合(源码定义见 pkg/apis/eksctl.io/v1alpha5/iam.go 中的 ClusterIAMServiceAccount 结构体)。

在动手之前,请先注意以下两条重要约束:

  • IRSA 要求 EKS 集群的 Kubernetes 版本为 1.13 及以上;
  • 如果你此前使用 实例角色(instance roles) 并打算改用 IRSA,不要混用两者。

IRSA 的底层工作原理

三个关键环节

  1. IAM OIDC Provider:IRSA 依赖 EKS 集群暴露的 OpenID Connect(OIDC)身份端点。IAM Role 的信任策略必须引用该集群专属的 OIDC Provider ARN,并限定可被信任的 Service Account 主体。

  2. Service Account 注解:Role 创建成功后,Service Account 上需要标注该 Role 的 ARN。eksctl 在创建/更新 iamserviceaccount 时会默认自动写入注解 eks.amazonaws.com/role-arn;如果你希望由其他工具(如 Helm)来维护这个注解,可以加 --role-only 只创建 Role 不动 Service Account。

  3. Pod 身份注入:EKS 集群内运行着 amazon-eks-pod-identity-webhook 准入控制器。当 Pod 使用带注解的 Service Account 启动时,Webhook 会向 Pod 注入 AWS 会话凭证,并通过 AWS_ROLE_ARN 与 AWS_WEB_IDENTITY_TOKEN_FILE 两个环境变量暴露给应用。只要应用使用较新版本的 AWS SDK(具体版本要求以 AWS 官方文档为准),SDK 就会自动利用这些凭证访问 AWS 服务。

信任策略的源码级生成逻辑

信任策略文档由 eksctl 的 OIDC 管理器构造。在 pkg/iam/oidc/api.go 中可以清楚看到两种模式:

  • 默认模式(MakeAssumeRolePolicyDocumentWithServiceAccountConditions):生成 StringEquals 条件,将 oidc.eks.<region>.amazonaws.com/id/<provider-id>:sub 精确限定为 system:serviceaccount:<namespace>:<name>,同时用 StringEquals 校验 :aud(audience);
  • 通配模式(MakeAssumeRolePolicyDocumentWithServiceAccountConditionsAllowingWildcard):将 :sub 条件改为 StringLike,允许通配符匹配多个 Service Account,:aud 仍保持精确匹配。

而在 pkg/cfn/builder/iam.go 的 makeAssumeRolePolicyDocument 中,IAMRoleResourceSet 会根据 spec.SubjectPattern 是否为空,决定调用上述哪一种生成函数——这就是 --subject-pattern 在底层生效的完整链路。

命令行方式创建 iamserviceaccount(不使用配置文件)

第一步:启用 IAM OIDC Provider

OIDC Provider 默认不开启。先执行:

eksctl utils associate-iam-oidc-provider --cluster=<clusterName>

第二步:创建 Role 与 Service Account

eksctl create iamserviceaccount --cluster=<clusterName> --name=<serviceAccountName> --namespace=<serviceAccountNamespace> --attach-policy-arn=<policyARN>
  • --attach-policy-arn 可以指定多次,用于同时附加多份 IAM 策略;
  • --namespace 缺省为 default;如果指定了不存在的命名空间,eksctl 会自动创建。

例如,创建一个对 S3 只读访问的 Service Account:

eksctl create iamserviceaccount --cluster=<clusterName> --name=s3-read-only --attach-policy-arn=arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

指定命名空间版本:

eksctl create iamserviceaccount --cluster=<clusterName> --name=s3-read-only --namespace=s3-app --attach-policy-arn=arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

如果集群里已存在同名 Service Account(但还没有绑定 IAM Role),需要加 --override-existing-serviceaccounts 才会更新它。这一行为与源码中的过滤逻辑一致:见 pkg/ctl/cmdutils/filter/iamserviceaccount_filter.go 的 SetExcludeExistingFilter——默认会把「已存在的 Service Account」排除出待创建集合,仅当 overrideExistingServiceAccounts=true 时跳过该排除。

给 IAM Role 打标签与自定义角色名

给 Role 添加自定义标签:

eksctl create iamserviceaccount --cluster=<clusterName> --name=<serviceAccountName> --tags "Owner=John Doe,Team=Some Team"

CloudFormation 默认会生成一个含随机字符串的 Role 名称;若想固定名称,用 --role-name:

eksctl create iamserviceaccount --cluster=<clusterName> --name=<serviceAccountName> --role-name "custom-role-name"

进阶:--role-only 与 --attach-role-arn

当 Service Account 由 Helm 等其他工具创建和管理时,为避免冲突,使用 --role-only 只创建 IAM Role、不创建也不注解 Service Account,role ARN 注解由外部工具负责维护:

eksctl create iamserviceaccount --cluster=<clusterName> --name=<serviceAccountName> --role-only --role-name=<customRoleName>

注意:--override-existing-serviceaccounts 对 --role-only(即配置中的 roleOnly)不生效,Role 始终会被创建。这一点在 pkg/ctl/create/iamserviceaccount.go 的日志逻辑中也有明确提示。

如果你已经有一个现成 Role 想直接复用(而不是让 eksctl 从策略生成),改用 --attach-role-arn 传入该 Role 的 ARN,并确保其信任策略只允许目标 Service Account 担任(trust relationship policy document 需按 AWS 官方 IRSA 技术文档配置):

eksctl create iamserviceaccount --cluster=<clusterName> --name=<serviceAccountName> --attach-role-arn=<customRoleARN>

更新与删除

  • 更新 Service Account 的权限:eksctl update iamserviceaccount;
  • 删除:eksctl delete iamserviceaccount。注意:该命令会删除 Kubernetes 中的 ServiceAccount,即使它并非由 eksctl 创建。

更新与删除的底层实现分别在 pkg/actions/irsa/update.go 和 pkg/actions/irsa/delete.go,二者都基于 CloudFormation Stack 管理:更新时按 eksctl-<cluster>-addon-iamserviceaccount-<namespace>-<name> 的命名规则定位已有 Stack(见 makeIAMServiceAccountStackName),删除时则先删 IAM Role Stack 再处理 Service Account。

进阶用法:--subject-pattern 通配信任多个 Service Account

当需要把同一 IAM 权限授予多个遵循命名规律的 Service Account 时,可用 --subject-pattern 创建信任通配模式的 IAM Role。典型场景包括:

  • 动态命名的多副本部署(deployment replicas);
  • 应用按可预测前缀批量创建 Service Account;
  • 多租户环境中共享一套命名约定的 Service Account。

使用 --subject-pattern 后,IAM 信任策略会从 StringEquals 改为 StringLike 条件运算符,允许 * 等通配符匹配多个 Service Account:

eksctl create iamserviceaccount \
  --cluster=<clusterName> \
  --name=<serviceAccountName> \
  --namespace=<serviceAccountNamespace> \
  --attach-policy-arn=<policyARN> \
  --subject-pattern="app-*"

例如,允许 default 命名空间中所有以 app- 开头的 Service Account 担任该 Role:

eksctl create iamserviceaccount \
  --cluster=<clusterName> \
  --name=app-base \
  --namespace=default \
  --attach-policy-arn=arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
  --subject-pattern="app-*"

生成的信任策略条件形如:

"StringLike": {
  "oidc.eks.region.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E:sub": "system:serviceaccount:default:app-*"
}

⚠️ 安全提醒:通配模式请务必谨慎使用。过宽的 pattern(如裸的 *)会允许命名空间内任意 Service Account 担任该 Role。应始终为你的使用场景选择最严格、最具体的模式。从源码看,--subject-pattern 由 pkg/ctl/create/iamserviceaccount.go 注册,其 JSON 字段为 subjectPattern(见 pkg/apis/eksctl.io/v1alpha5/iam.go),StringLike 的生成逻辑见 pkg/iam/oidc/api.go。

使用配置文件(ClusterConfig)管理 iamserviceaccount

所有 iamserviceaccount 相关命令都支持 --config-file,管理方式与 nodegroups 一致。

配置骨架

在 ClusterConfig 中设置 iam.withOIDC: true,并在 iam.serviceAccounts 下列出所有账户:

# 完整示例见仓库 examples/13-iamserviceaccounts.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: cluster-13
  region: us-west-2

iam:
  withOIDC: true
  serviceAccounts:
  - metadata:
      name: s3-reader
      namespace: backend-apps   # 不写则默认 "default";命名空间不存在会自动创建
      labels: {aws-usage: "application"}
    attachPolicyARNs:
    - "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
    tags:
      Owner: "John Doe"
      Team: "Some Team"
    subjectPattern: "app-*"
  - metadata:
      name: cache-access
      namespace: backend-apps
      labels: {aws-usage: "application"}
    attachPolicyARNs:
    - "arn:aws:iam::aws:policy/AmazonDynamoDBReadOnlyAccess"
    - "arn:aws:iam::aws:policy/AmazonElastiCacheFullAccess"
  - metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels: {aws-usage: "cluster-ops"}
    wellKnownPolicies:
      autoScaler: true
    roleName: eksctl-cluster-autoscaler-role
    roleOnly: true
  - metadata:
      name: some-app
      namespace: default
    attachRoleARN: arn:aws:iam::123:role/already-created-role-for-app
nodeGroups:
  - name: "ng-1"
    tags:
      # cluster-autoscaler 自动发现所需的 EC2 标签
      k8s.io/cluster-autoscaler/enabled: "true"
      k8s.io/cluster-autoscaler/cluster-13: "owned"
    desiredCapacity: 1

这份配置可以直接配合 eksctl create cluster 使用。如果集群已经创建但未设置这些字段,可用以下两条命令补齐:

eksctl utils associate-iam-oidc-provider --config-file=<path>
eksctl create iamserviceaccount --config-file=<path>

配置项说明(源码依据)

  • metadata.name / metadata.namespace:Service Account 名称与命名空间,对应 ClusterIAMMeta;
  • metadata.labels:随 Service Account 一起打上的标签;
  • attachPolicyARNs:要附加的 IAM 策略 ARN 列表(对应命令行 --attach-policy-arn,可多次);
  • attachPolicy:可直接内联一份 IAM 策略文档(详见 examples/13-iamserviceaccounts.yaml 中的 autoscaler-service 示例),与 attachPolicyARNs 可同时使用;
  • attachRoleARN:复用已有 IAM Role(对应 --attach-role-arn);
  • roleName:固定 Role 名称(对应 --role-name);
  • roleOnly:只创建 Role 不管理 Service Account(对应 --role-only);
  • tags:附加到 IAM Role 的标签;
  • subjectPattern:信任策略的通配模式(对应 --subject-pattern);
  • wellKnownPolicies:为常见用例(cluster-autoscaler、cert-manager、aws-load-balancer-controller、external-dns、ebs/efs-csi-controller、imageBuilder 等)提供策略速写,完整字段见 pkg/apis/eksctl.io/v1alpha5/well_known_iam_policy.go 中的 WellKnownPolicies 结构体。

serviceAccounts 所有属性均已写入配置模式文件 pkg/apis/eksctl.io/v1alpha5/assets/schema.json(含 subjectPattern、roleOnly、attachRoleARN 等字段定义),可用于 IDE 校验与自动补全。

按名称过滤:--include / --exclude / --only-missing

  • eksctl create iamserviceaccount 支持 --include / --exclude(用法细节参见 nodegroups 文档 中关于 include/exclude 规则的说明);
  • eksctl delete iamserviceaccount 额外支持 --only-missing,可只删除「配置中不存在、但集群里存在」的 iamserviceaccount,行为与 nodegroups 一致。

注意:iamserviceaccount 是命名空间作用域的,不同命名空间可以存在同名账户。因此 --include / --exclude 必须使用 namespace/name 格式的唯一标识,例如:

eksctl create iamserviceaccount --config-file=<path> --include backend-apps/s3-reader

这一命名约定的源码依据是 ClusterIAMServiceAccount.NameString()(返回 namespace/name),以及过滤器的 SetDeleteFilter 实现(pkg/ctl/cmdutils/filter/iamserviceaccount_filter.go),后者会对比配置与集群远程状态,自动剔除「配置中有但集群中缺失」或(在 --only-missing 下)「两边都有」的账户。

与 EKS Pod Identity Associations 的关系与选择

eksctl 目前推荐优先考虑更新的方案 —— EKS Pod Identity Associations:

  • IRSA 的 IAM Role 信任策略必须引用某个集群专属的 OIDC Provider,因此 Role 与集群强绑定,跨集群复用需要重复配置信任策略;
  • Pod Identity Association 直接通过 EKS API 配置,不再需要操作 IAM API 引用 OIDC Provider,Role 不再绑定单一集群,可跨多个 EKS 集群复用,简化了自动化与角色管理;
  • 它仍需在集群上安装 eks-pod-identity-agent 插件(eksctl create addon --cluster my-cluster --name eks-pod-identity-agent),并且使用已有 Role 时同样要配置信任关系(Principal 为服务主体 pods.eks.amazonaws.com)。

不过,本文所述的 IRSA 方案依然被广泛使用、文档资料成熟,在存量集群迁移或对 Webhook 注入机制有特定需求时仍然是可靠选择。可以在两者之间按上述差异权衡。

关键命令速查表

目的 命令
启用 IAM OIDC Provider eksctl utils associate-iam-oidc-provider --cluster=<clusterName>
创建 iamserviceaccount(CLI) eksctl create iamserviceaccount --cluster=<name> --name=<sa> --namespace=<ns> --attach-policy-arn=<ARN>
只创建 Role 不碰 ServiceAccount eksctl create iamserviceaccount --cluster=<name> --name=<sa> --role-only --role-name=<role>
复用已有 Role eksctl create iamserviceaccount --cluster=<name> --name=<sa> --attach-role-arn=<ARN>
通配信任多个 Service Account eksctl create iamserviceaccount --cluster=<name> --name=<sa> --subject-pattern="app-*"
更新权限 eksctl update iamserviceaccount ...
删除(含非 eksctl 创建的 SA) eksctl delete iamserviceaccount ...
按配置批量管理 eksctl create/update/delete iamserviceaccount --config-file=<path> [--include ns/name] [--only-missing]

延伸阅读

登录后查看全文
eksctl