eksctl 实战:使用 IAM Roles for Service Accounts(IRSA)为 EKS 应用绑定细粒度 AWS 权限
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 的底层工作原理
三个关键环节
-
IAM OIDC Provider:IRSA 依赖 EKS 集群暴露的 OpenID Connect(OIDC)身份端点。IAM Role 的信任策略必须引用该集群专属的 OIDC Provider ARN,并限定可被信任的 Service Account 主体。
-
Service Account 注解:Role 创建成功后,Service Account 上需要标注该 Role 的 ARN。eksctl 在创建/更新 iamserviceaccount 时会默认自动写入注解
eks.amazonaws.com/role-arn;如果你希望由其他工具(如 Helm)来维护这个注解,可以加--role-only只创建 Role 不动 Service Account。 -
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] |
延伸阅读
- EKS Pod Identity Associations(更新的细粒度权限方案)
- 实例角色(instance roles)与 IAM 策略说明
- 将 IAM 用户/角色映射到 Kubernetes RBAC
- 完整示例配置:examples/13-iamserviceaccounts.yaml
- 核心源码:命令入口 pkg/ctl/create/iamserviceaccount.go、类型定义 pkg/apis/eksctl.io/v1alpha5/iam.go、信任策略生成 pkg/iam/oidc/api.go 与 pkg/cfn/builder/iam.go、生命周期管理 pkg/actions/irsa