eksctl 0.165.0 核心特性:EKS Pod Identity Associations 配置与迁移实战指南

原创2026-10-12 12:35:241,908 阅读
文章标签:云原生容器编排DevOps

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 角色创建/迁移实现的体系。仓库中围绕该特性形成了完整闭环:

二、背景:为什么 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 注解绑定角色。这带来两个痛点:

  1. 角色与集群强耦合:信任策略引用特定集群的 OIDC provider,角色无法直接跨集群复用;
  2. 自动化复杂度高:每创建一个新集群都需要更新角色的信任策略,容易造成角色重复与运维负担。

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 的任务编排)依次为:

  1. 若集群未启用 eks-pod-identity-agent 插件,先自动安装;
  2. 识别所有与 iamserviceaccounts 关联的 IAM 角色(通过服务账户上的 eks.amazonaws.com/role-arn 注解与 CloudFormation 栈清单);
  3. 识别所有与支持 Pod Identity 的 EKS Addons 关联的 IAM 角色;
  4. 为识别出的全部角色更新信任策略:新增指向 pods.eks.amazonaws.com Service Principal 的信任实体,并可选移除原有 OIDC Provider 信任关系;
  5. 为 iamserviceaccounts 对应的角色创建 Pod Identity Association;
  6. 更新 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)。

十、延伸阅读

登录后查看全文
eksctl