eksctl 0.165.0 核心特性:EKS Pod Identity Associations 配置与迁移实战指南
eksctl 0.165.0 核心特性:EKS Pod Identity Associations 配置与迁移实战指南
本指南以 eksctl v0.165.0 发布的核心特性——EKS Pod Identity Associations 支持(PR #7312、#7313、#7315)为主线,完整介绍如何在集群创建阶段与创建后通过 eksctl 配置、查询、更新和删除 Pod Identity Association,并深入讲解其与 EKS Add-ons 的联动、跨账户访问支持以及从 IRSA(iamserviceaccounts)一键迁移的落地方法。读完本文,你将能够使用 eksctl 配置文件的 iam.podIdentityAssociations 字段与 eksctl create/get/update/delete podidentityassociation 系列命令,独立完成应用 IAM 权限的声明式管理。
一、v0.165.0 版本概览:Pod Identity Associations 正式落地
版本发布说明 是 eksctl 围绕 Pod Identity 的一次关键迭代,其内容分布如下:
- 🚀 Features(核心特性):新增对 EKS Pod Identity Associations 的完整支持(#7312、#7313、#7315)。
- 🧰 Maintenance(维护工作):为链接检查器忽略 google docs 域名(#7316)、升级 aws-sdk 依赖(#7292)、常规依赖升级(#7267)、改进 CRUD 集成测试套件运行时间(#7208)。
- 📝 Documentation(文档):修复 README 链接(#7230)。
该版本所引入的 Pod Identity 支持并非一个孤立命令,而是一整套从配置文件字段、CLI 子命令到内部 IAM 角色创建/迁移实现的体系。仓库中围绕该特性形成了完整闭环:
- 配置结构:
PodIdentityAssociation定义于pkg/apis/eksctl.io/v1alpha5/iam.go,挂载在iam.podIdentityAssociations字段下; - 增删改查实现:
pkg/actions/podidentityassociation/包内的 creator.go、getter.go、updater.go、deleter.go; - CLI 命令入口:create、以及
pkg/ctl/cmdutils/pod_identity_association.go中的参数校验逻辑; - 完整示例配置:examples/39-pod-identity-association.yaml。
二、背景:为什么 EKS 引入 Pod Identity Association
在 Pod Identity 出现之前,Kubernetes 应用访问 AWS 服务主要依赖 IRSA(IAM Roles for Service Accounts)。IRSA 的核心机制是:集群启用 OIDC Provider,IAM 角色的信任策略中必须引用该 OIDC Provider 的 URL,服务账户通过 eks.amazonaws.com/role-arn 注解绑定角色。这带来两个痛点:
- 角色与集群强耦合:信任策略引用特定集群的 OIDC provider,角色无法直接跨集群复用;
- 自动化复杂度高:每创建一个新集群都需要更新角色的信任策略,容易造成角色重复与运维负担。
EKS Pod Identity Association 则是直接通过 EKS API 将服务账户与 IAM 角色建立关联,底层由运行在节点上的 DaemonSet——EKS Pod Identity Agent 负责向 Pod 注入临时凭证。正如 Pod Identity 用户指南 所述,IAM 角色不再需要引用 OIDC provider,因而不再绑定单一集群,可以跨多个 EKS 集群复用,无需每次新建集群都修改信任策略。
从源码角度看,这一"去 OIDC"特性有直接证据:在迁移场景中,tasks.go 的 updateTrustStatements 会识别信任策略中 Principal 为 Federated 且值包含 oidc-provider 的语句,并在需要时将其移除,替换为 EKS 的 Service Principal 信任语句(pods.eks.amazonaws.com)。
三、前置条件:Pod Identity Agent 与角色信任策略
3.1 安装 eks-pod-identity-agent 插件
Pod Identity 的底层实现依赖 Agent 以 DaemonSet 形式运行在工作节点上。因此,创建 Pod Identity Association 之前,集群必须已安装 EKS Pod Identity Agent 插件,使用 eksctl 安装方式与其他 Addon 一致:
eksctl create addon --cluster my-cluster --name eks-pod-identity-agent
注意:如果你使用的是 EKS Auto Mode 集群,eks-pod-identity-agent 已预装,可以跳过此步。
源码中对此有硬性检查:在 create/pod_identity_association.go 中,命令执行前会调用 IsPodIdentityAgentInstalled 探测插件是否可用;未安装时返回 ErrPodIdentityAgentNotInstalled,并提示用上述命令启用。而 migrator.go 中的检查逻辑还额外识别 Auto Mode 集群(IsAutoModeEnabled 探测 ComputeConfig.Enabled),两种场景都会视为 Agent 已就绪。
3.2 复用现有 IAM 角色时的信任策略
如果为 Pod Identity Association 指定一个已存在的 IAM 角色(roleARN),必须先让该角色信任新的 EKS Service Principal pods.eks.amazonaws.com:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "pods.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
如果你不提供 roleARN,eksctl 会在后台自动创建 IAM 角色并配置上述信任策略(详见下文第四节源码剖析)。
四、核心配置:iam.podIdentityAssociations 字段全解
Pod Identity 的一切操作都围绕 ClusterConfig 中的 iam.podIdentityAssociations 字段展开,字段定义见 pkg/apis/eksctl.io/v1alpha5/iam.go。其通用结构如下:
iam:
podIdentityAssociations:
- namespace: <string> # 必填
serviceAccountName: <string> # 必填
createServiceAccount: true # 可选,默认 false
roleARN: <string> # 与下列三个字段互斥(见下方说明)
roleName: <string> # 可选,未提供时自动生成,提供 roleARN 时被忽略
permissionPolicy: {} # 可选,内联权限策略文档
permissionPolicyARNs: [] # 可选,预置策略 ARN 列表
wellKnownPolicies: {} # 可选,常用策略快捷方式
permissionsBoundaryARN: <string> # 可选,角色权限边界
tags: {} # 可选,附加到关联的 AWS 标签
字段语义与约束(依据 cmdutils/pod_identity_association.go 的校验逻辑):
| 字段 | 必填性 | 说明 |
|---|---|---|
namespace |
必填 | 服务账户所属命名空间 |
serviceAccountName |
必填 | 要关联的 Kubernetes 服务账户名称 |
createServiceAccount |
可选 | 为 true 时由 eksctl 创建服务账户(默认 false,即要求服务账户已存在) |
roleARN |
条件必填 | 指定已有 IAM 角色 ARN;与 permissionPolicy、permissionPolicyARNs、wellKnownPolicies 互斥,且一旦设置,这三者均不可同时出现 |
roleName |
可选 | 指定自动创建角色的名称;不提供时自动生成 |
permissionPolicy |
可选 | 内联权限策略(JSON 文档),作为角色权限策略 |
permissionPolicyARNs |
可选 | 要附加的托管策略 ARN 列表 |
wellKnownPolicies |
可选 | 快捷绑定常用策略,如 autoScaler、externalDNS、imageBuilder、awsLoadBalancerController、certManager、ebsCSIController、efsCSIController(定义见 well_known_iam_policy.go) |
permissionsBoundaryARN |
可选 | 为自动创建的角色设置权限边界 |
tags |
可选 | AWS 标签 |
校验规则中有一条值得注意:创建时必须满足 roleARN、permissionPolicy、permissionPolicyARNs、wellKnownPolicies 四者至少其一;而 roleARN 一旦给出,其他三个字段必须为空,否则报错(对应配置路径如 iam.podIdentityAssociations[0].permissionPolicyARNs cannot be specified when iam.podIdentityAssociations[0].roleARN is set)。此外,namespace 与 serviceAccountName 缺失也会直接报错。
4.1 完整示例解读
仓库提供了覆盖全部三种"权限来源"模式的完整示例 examples/39-pod-identity-association.yaml,其核心片段如下。
模式一:使用已有角色(仅创建关联)
addons:
- name: eks-pod-identity-agent # iam.podIdentityAssociations 的前置依赖
iam:
podIdentityAssociations:
- namespace: default
serviceAccountName: s3-reader
createServiceAccount: true # 默认 false
roleARN: arn:aws:iam::111122223333:role/role-1
模式二:由 eksctl 创建角色(基于托管策略/常用策略)
- namespace: dev
serviceAccountName: app-cache-access
roleName: pod-identity-role-app-cache
permissionPolicyARNs: ["arn:aws:iam::111122223333:policy/permission-policy-1", "arn:aws:iam::111122223333:policy/permission-policy-2"]
wellKnownPolicies:
autoScaler: true
externalDNS: true
permissionsBoundaryARN: arn:aws:iam::111122223333:policy/permission-boundary
模式三:由 eksctl 创建角色(基于内联权限策略)
- namespace: dev
serviceAccountName: nginx
permissionPolicy:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action:
- "autoscaling:DescribeAutoScalingGroups"
- "autoscaling:SetDesiredCapacity"
- "autoscaling:TerminateInstanceInAutoScalingGroup"
- "ec2:DescribeLaunchTemplateVersions"
Resource: '*'
三种模式的分工清晰:提供 roleARN 时 eksctl 只做关联;不提供时,eksctl 依据 permissionPolicyARNs / wellKnownPolicies / permissionPolicy 自动创建角色。
4.2 源码层面的角色创建原理
当配置中不含 roleARN 时,创建流程(creator.go)会为每个关联构建一个子任务序列:创建 IAM 角色 →(可选)创建服务账户 → 调用 EKS API 创建 Pod Identity Association。
角色资源由 pkg/cfn/builder/iam.go 的 NewIAMRoleResourceSetForPodIdentity 构建 CloudFormation 模板:以 permissionPolicy 作为内联策略、permissionPolicyARNs 附加托管策略、wellKnownPolicies 绑定常用策略、permissionsBoundaryARN 设置权限边界。角色栈命名遵循 iam_role_creator.go 中的约定:
eksctl-<cluster>-podidentityrole-<namespace>-<serviceAccountName>
角色创建完成后,其 ARN 会回填到关联对象的 RoleARN 字段,随后通过 EKS API 的 CreatePodIdentityAssociation 建立关联(见 tasks.go)。
五、增删改查:四种场景的完整命令
5.1 创建(Create)
方式一:集群创建阶段——在配置文件中声明 iam.podIdentityAssociations,随集群一起创建:
eksctl create cluster -f config.yaml
方式二:集群创建后,使用配置文件:
eksctl create podidentityassociation -f config.yaml
方式三:集群创建后,使用 CLI 标志:
eksctl create podidentityassociation \
--cluster my-cluster \
--namespace default \
--service-account-name s3-reader \
--permission-policy-arns="arn:aws:iam::111122223333:policy/permission-policy-1, arn:aws:iam::111122223333:policy/permission-policy-2" \
--well-known-policies="autoScaler,externalDNS" \
--permissions-boundary-arn arn:aws:iam::111122223333:policy/permissions-boundary
CLI 标志与配置文件字段的对应关系(定义于 create/pod_identity_association.go):
| CLI 标志 | 对应配置字段 |
|---|---|
--namespace |
namespace |
--service-account-name |
serviceAccountName |
--role-arn |
roleARN |
--role-name |
roleName |
--permission-boundary-arn |
permissionsBoundaryARN |
--permission-policy-arns |
permissionPolicyARNs |
--well-known-policies |
wellKnownPolicies |
--create-service-account |
createServiceAccount |
--target-role-arn |
targetRoleARN(跨账户) |
--disable-session-tags |
disableSessionTags |
--policy |
policy(附加限制策略) |
--tags |
tags |
配置文件中没有 permissionPolicy 的 CLI 对应项——它是唯一只能通过配置文件声明的字段(内联策略文档无法以标志表达)。同时注意:配置文件方式与上述 CLI 标志互斥,混用会触发校验错误。
重要限制:一个服务账户同一时间只能关联一个 IAM 角色,因此为同一服务账户创建第二个 Pod Identity Association 会报错。
5.2 查询(Get)
查询集群上全部关联:
eksctl get podidentityassociation -f config.yaml
# 或
eksctl get podidentityassociation --cluster my-cluster
只查某个命名空间:
eksctl get podidentityassociation --cluster my-cluster --namespace default
查某个服务账户对应的单个关联:
eksctl get podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader
输出结果可通过 --output json 转为 JSON。从源码看(getter.go),查询流程先调用 ListPodIdentityAssociations 过滤,再逐个 DescribePodIdentityAssociation 拉取详情,返回 AssociationARN、Namespace、ServiceAccountName、RoleARN 以及(当关联由 EKS Addons API 管理时)OwnerARN。
5.3 更新(Update)
方式一:配置文件——修改 roleARN 后执行:
iam:
podIdentityAssociations:
- namespace: default
serviceAccountName: s3-reader
roleARN: new-role-arn-1
- namespace: dev
serviceAccountName: app-cache-access
roleARN: new-role-arn-2
eksctl update podidentityassociation -f config.yaml
方式二:CLI 标志——更新单个关联:
eksctl update podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader --role-arn new-role-arn
更新命令同样支持 --target-role-arn、--disable-session-tags、--policy 标志,用于调整跨账户相关设置。
5.4 删除(Delete)
方式一:配置文件——只需给出 namespace 与 serviceAccountName:
iam:
podIdentityAssociations:
- namespace: default
serviceAccountName: s3-reader
- namespace: dev
serviceAccountName: app-cache-access
eksctl delete podidentityassociation -f config.yaml
方式二:CLI 标志:
eksctl delete podidentityassociation --cluster my-cluster --namespace default --service-account-name s3-reader
从 deleter.go 的实现看,删除会先通过 ListPodIdentityStackNames 定位 eksctl 创建的 IAM 角色栈,随后并行执行 EKS API 删除关联与 CloudFormation 删除角色栈,保证由 eksctl 创建的角色被一并清理。
六、与 EKS Add-ons 的联动
6.1 三个配置入口
EKS Add-ons 同样可以通过 Pod Identity 获得 IAM 权限,配置文件为此暴露三个字段:
| 字段 | 位置 | 作用 |
|---|---|---|
addon.podIdentityAssociations |
单个 addon 内 | 显式声明该 addon 的 Pod Identity 关联 |
addonsConfig.autoApplyPodIdentityAssociations |
顶层 | 创建 addon 时自动解析并应用 EKS 推荐的 Pod Identity 配置 |
addon.useDefaultPodIdentityAssociations |
单个 addon 内 | 迁移场景:使用 EKS API 推荐的 Pod Identity 关联(见 addon.go) |
注意:并非所有 EKS Add-ons 都支持 Pod Identity。不支持的 addon 仍应使用 IRSA 方式提供 IAM 权限。
6.2 创建带 IAM 权限的 addon
在配置文件中显式声明 addon.podIdentityAssociations,eksctl 会优先使用它来配置 addon 的 IAM 权限:
addons:
- name: vpc-cni
podIdentityAssociations:
- serviceAccountName: aws-node
permissionPolicyARNs: ["arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"]
eksctl create addon -f config.yaml
# 输出示例:
# 2024-05-13 15:38:58 [ℹ] pod identity associations are set for "vpc-cni" addon; will use these to configure required IAM permissions
限制:同一 addon 同时配置 Pod Identity 与 IRSA 是不允许的,会触发校验错误。从 validation.go 的 validateAddonPodIdentityAssociations 可以看到,addon.podIdentityAssociations 中不支持 wellKnownPolicies,需要时请改用 useDefaultPodIdentityAssociations。
6.3 自动应用推荐的 Pod Identity 配置
对支持 Pod Identity 的 addon,只需设置 addonsConfig.autoApplyPodIdentityAssociations: true:
addonsConfig:
autoApplyPodIdentityAssociations: true
# 注意:若 addon 已显式配置了 pod identity 或 IRSA,或该 addon 本身不支持 pod identity,
# 此开关不会生效。
addons:
- name: vpc-cni
eksctl create addon -f config.yaml
# 输出示例:
# [ℹ] "addonsConfig.autoApplyPodIdentityAssociations" is set to true; will lookup recommended pod identity configuration for "vpc-cni" addon
等价 CLI 方式:
eksctl create addon --cluster my-cluster --name vpc-cni --auto-apply-pod-identity-associations
6.4 更新与删除 addon 的 Pod Identity
更新 addon 时,addon.podIdentityAssociations 是目标状态的唯一事实来源(single source of truth)。eksctl 会比较期望状态与集群现状,自动执行三类操作:
- 创建:配置文件中存在、集群中缺失的关联(连同 IAM 资源);
- 删除:配置文件中已移除的关联(连同其 IAM 资源);
- 更新:两侧都存在但 IAM 权限集合发生变化的关联。
eksctl update addon -f config.yaml 的典型输出会依次显示"更新 IAM 资源栈 → 创建/删除角色栈 → 更新 addon"的过程。若要移除 addon 的全部 Pod Identity 关联,必须显式将 podIdentityAssociations 置为 [](省略该字段反而会触发校验错误):
addons:
- name: vpc-cni
podIdentityAssociations: []
eksctl update addon -f config.yaml
删除 addon(eksctl delete addon)会连带删除其全部 Pod Identity 关联及由 eksctl 创建的相关 IAM 角色;删除集群则对所有 addon 达到同样效果。
重要提醒:由 EKS Addons API 托管的关联,其生命周期归 addon 所有。因此,对这类关联不要使用 eksctl update podidentityassociation 或 eksctl delete podidentityassociation 直接操作,而应通过 eksctl update addon / eksctl delete addon 管理。判断依据是查询结果中的 OwnerARN 字段:当 OwnerARN 被填充(形如 arn:aws:eks:<region>:<account>:addon/<cluster>/<addon>/<uuid>)时,即表示该关联的生命周期由 EKS Addons API 控制。
七、迁移:从 IRSA 一键切换到 Pod Identity
对于存量集群,eksctl 提供了 utils migrate-to-pod-identity 命令,将现有 iamserviceaccounts(IRSAv1)与 EKS Addons 使用的 IAM 角色迁移到 Pod Identity:
eksctl utils migrate-to-pod-identity --cluster my-cluster --approve
其执行步骤(对应 migrator.go 的任务编排)依次为:
- 若集群未启用
eks-pod-identity-agent插件,先自动安装; - 识别所有与 iamserviceaccounts 关联的 IAM 角色(通过服务账户上的
eks.amazonaws.com/role-arn注解与 CloudFormation 栈清单); - 识别所有与支持 Pod Identity 的 EKS Addons 关联的 IAM 角色;
- 为识别出的全部角色更新信任策略:新增指向
pods.eks.amazonaws.comService Principal 的信任实体,并可选移除原有 OIDC Provider 信任关系; - 为 iamserviceaccounts 对应的角色创建 Pod Identity Association;
- 更新 EKS Addons(由 EKS API 在后台创建 addon 的 Pod Identity)。
不带 --approve 时命令只输出计划(plan),展示将要执行的完整任务树(如"更新 owned/unowned 角色的信任策略 → 迁移 addon → 创建关联"的嵌套结构),并以"all tasks were skipped / no changes were applied"结尾。
OIDC 信任关系的处理:addon 关联的角色总是移除 OIDC 信任关系;而 iamserviceaccounts 关联的角色默认保留 OIDC 信任关系(保证平滑过渡),如需一并移除,追加标志:
eksctl utils migrate-to-pod-identity --cluster my-cluster --approve --remove-oidc-provider-trust-relationship
加上该标志后,迁移还会顺带移除服务账户上的 IRSAv1 注解 eks.amazonaws.com/role-arn(见 migrator.go)。
八、跨账户 Pod Identity 支持
eksctl 支持 EKS Pod Identity 的跨账户访问:集群所在账户(源账户) 中的角色(roleARN)与资源所在账户(目标账户) 中的角色(targetRoleARN)建立链式信任,使 Pod 获得目标账户角色的临时凭证,从而访问另一账户的 AWS 资源。
使用前需先在两个账户分别配置好 IAM 角色与策略(源角色可被目标角色信任、目标角色授予相应资源权限)。配置示例如下(完整版见 examples/39-pod-identity-association.yaml):
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: my-cluster
region: us-west-2
addons:
- name: eks-pod-identity-agent
iam:
podIdentityAssociations:
- namespace: default
serviceAccountName: demo-app-sa
createServiceAccount: true
# 与集群同账户的源角色
roleARN: arn:aws:iam::1111111111:role/account-a-role
# 不同账户的目标角色
targetRoleARN: arn:aws:iam::2222222222:role/account-b-role
# 可选:禁用 EKS Pod Identity 自动添加的会话标签
disableSessionTags: false
关联字段定义于 iam.go:targetRoleARN(目标角色,实现跨账户链式访问)与 disableSessionTags(是否禁用 EKS 自动注入的会话标签)。在调用 EKS API 时(tasks.go),只要 targetRoleARN 非空就会被写入 CreatePodIdentityAssociationInput.TargetRoleArn。
仓库示例还提供了两种跨账户变体:一是 roleARN + targetRoleARN 的组合;二是只给 roleName + permissionPolicyARNs(不指定 roleARN),由 eksctl 先创建源账户角色(该角色权限策略必须允许代入 targetRoleARN),再配合 targetRoleARN 完成跨账户链式信任。
九、常见约束与注意事项小结
- Agent 前置依赖:任何 Pod Identity 创建/迁移操作都要求集群已安装
eks-pod-identity-agent(Auto Mode 集群除外),否则命令直接报错并提示安装命令。 - 角色-服务账户一对一:同一服务账户同一时间只能有一个关联,重复创建会报错。
roleARN互斥规则:提供roleARN时不得同时声明permissionPolicy、permissionPolicyARNs、wellKnownPolicies。- addon 内不支持 wellKnownPolicies:addon 的
podIdentityAssociations中只能用permissionPolicyARNs等,需用推荐策略时改用useDefaultPodIdentityAssociations。 - addon 关联的生命周期归属:
OwnerARN非空的关联归 EKS Addons API 管理,请用eksctl update/delete addon而非 podidentityassociation 子命令。 - 移除全部关联须显式置空:
podIdentityAssociations: []是删除 addon 全部关联的唯一合法写法。 - 配置文件与 CLI 标志互斥:
create/get/update/delete podidentityassociation系列命令中,配置文件方式与对应的 CLI 标志不能混用(相关标志列表见 cmdutils/pod_identity_association.go)。
十、延伸阅读
- 完整示例配置:examples/39-pod-identity-association.yaml
- 特性用户指南:userdocs/src/usage/pod-identity-associations.md
- 配置结构定义:pkg/apis/eksctl.io/v1alpha5/iam.go
- 核心实现:pkg/actions/podidentityassociation/creator.go、pkg/actions/podidentityassociation/getter.go、pkg/actions/podidentityassociation/deleter.go、pkg/actions/podidentityassociation/migrator.go
- CLI 入口与校验:pkg/ctl/create/pod_identity_association.go、pkg/ctl/cmdutils/pod_identity_association.go
- 相关命令:EKS Add-ons 创建与权限配置见 userdocs/src/usage/addons.md;IRSA 背景见 userdocs/src/usage/iamserviceaccounts.md;Auto Mode 说明见 userdocs/src/usage/auto-mode.md