eksctl 0.197.0 解析:Auto Mode 自定义 IAM 角色的能力补齐与 Hybrid Nodes 文档清理

原创2026-10-12 13:28:131,330 阅读
文章标签:云原生容器编排DevOps

eksctl 0.197.0 解析:Auto Mode 自定义 IAM 角色的能力补齐与 Hybrid Nodes 文档清理

导读:本文围绕 eksctl v0.197.0 版本发布说明展开,重点剖析该版本唯一的 Bug 修复——「为 Auto Mode 提供自定义 IAM 角色时自动补齐 IAM capability」,并从仓库源码层面还原该修复的完整实现链路(配置校验、角色创建、CloudFormation 能力声明),同时介绍同版本对 Hybrid Nodes 文档的清理工作。读完本文,你将理解 eksctl 在启用 Auto Mode、提供自定义节点角色(nodeRoleARN)时底层发生了什么,以及如何通过配置文件正确组合 autoModeConfig 与 capabilities 完成实际部署。

版本概览:一次聚焦的修复型发布

v0.197.0 是 eksctl 的一个小型修复型版本,改动集中在两处:

  • Bug Fixes:Add IAM capability if a custom IAM role is provided for Auto Mode (#8071)
  • Documentation:Cleanup Hybrid Nodes docs (#8072)

该版本致谢了外部贡献者 @geoffcline。与周边版本横向比较可以发现,0.195.0、0.203.0 等版本同样涉及 Hybrid Nodes 文档的持续调整,而 0.197.0 的核心工程价值在第一个修复项:它补齐了「用户为 Auto Mode 显式指定自定义 IAM 角色时,CloudFormation 栈缺少 CAPABILITY_IAM 能力声明」这一边界问题。

背景:Auto Mode 下的两种节点角色来源

EKS Auto Mode 允许集群完全接管节点生命周期,eksctl 通过 autoModeConfig 配置块(定义于 pkg/apis/eksctl.io/v1alpha5/auto_mode.go)来驱动这一能力:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: auto-mode-cluster
  region: us-west-2

autoModeConfig:
  enabled: true                 # 是否启用 Auto Mode,默认 false
  nodePools: [general-purpose, system]  # 可选,默认 [general-purpose, system]
  # nodeRoleARN: ""             # 可选;不提供时 eksctl 会自动创建角色

其中 NodeRoleARN(JSON 字段 nodeRoleARN)是节点角色 ARN,它的取值决定了 Auto Mode 节点的 IAM 角色来自哪里:

  • 不设置 nodeRoleARN:由 eksctl 通过 RoleCreator.CreateOrImport 自动创建(或从既有集群栈导入),栈名为 eksctl-<cluster>-auto-mode-role,见 pkg/automode/role_creator.go。
  • 设置 nodeRoleARN:直接复用用户提供的自定义角色,eksctl 不再创建角色栈。

两种路径中,只有前者天然会带上 IAM 能力声明,后者在 0.197.0 之前存在缺口——这正是 #8071 修复的内容。

修复剖析:自定义角色场景下 IAM capability 的补齐

配置侧:nodeRoleARN 的约束与校验

autoModeConfig 在配置层面有一组严格约束,由 ValidateAutoModeConfig 强制保证:

  • Auto Mode 不支持 Outposts(Auto Mode is not supported on Outposts);
  • nodeRoleARN 与空的 nodePools 互斥(cannot specify autoModeConfig.nodeRoleARN when autoModeConfig.nodePools is empty);
  • permissionsBoundaryARN 与 nodeRoleARN 互斥(cannot specify autoModeConfig.permissionBoundaryARN when autoModeConfig.nodeRoleARN is set);
  • nodePools 仅允许取值 general-purpose、system 且不可重复;
  • Auto Mode 关闭(enabled: false)时,不允许设置 nodeRoleARN、permissionsBoundaryARN 或 nodePools。

这些约束在 pkg/apis/eksctl.io/v1alpha5/auto_mode_validation_test.go 中均有对应的 Table-driven 测试用例覆盖,例如 both nodeRoleARN and nodePools specified、nodeRoleARN and nodePools specified when Auto Mode is disabled 等。

运行时:自定义角色如何被使用

当用户提供了 nodeRoleARN,Updater.enableAutoMode 会走以下分支逻辑:

if len(computeConfigReq.NodePools) > 0 {
    if currentClusterCompute != nil && currentClusterCompute.NodeRoleArn != nil {
        computeConfigReq.NodeRoleArn = currentClusterCompute.NodeRoleArn
    } else if autoModeConfig.NodeRoleARN.IsZero() {
        // 自动创建角色
        nodeRoleARN, err := u.RoleManager.CreateOrImport(ctx, clusterName)
        ...
        computeConfigReq.NodeRoleArn = aws.String(nodeRoleARN)
    } else {
        // 使用用户提供的自定义角色
        computeConfigReq.NodeRoleArn = aws.String(autoModeConfig.NodeRoleARN.String())
    }
}

对应地,auto_mode_updater_test.go 中用 enabling Auto Mode with a custom nodeRoleARN and node pools 这一用例覆盖了自定义角色的启用路径;同时还覆盖了 attempt to update nodeRoleARN 场景——一旦 Auto Mode 已启用,nodeRoleARN 不允许被修改(autoModeConfig.nodeRoleARN cannot be modified)。

能力声明:CAPABILITY_IAM 从哪里来

修复的核心在 CloudFormation 能力声明层。eksctl 在创建栈时通过 WithIAM() / WithNamedIAM() 两个方法决定是否附加 CAPABILITY_IAM / CAPABILITY_NAMED_IAM:

// pkg/cfn/manager/api.go
stackCapabilitiesIAM      = []types.Capability{types.CapabilityCapabilityIam}
stackCapabilitiesNamedIAM = []types.Capability{types.CapabilityCapabilityNamedIam}

在 DoCreateStackRequest 中:

if withIAM {
    input.Capabilities = stackCapabilitiesIAM
}
if withNamedIAM {
    input.Capabilities = stackCapabilitiesNamedIAM
}

对于 Auto Mode 自动创建角色栈的场景,AutoModeResourceSet.WithIAM 返回 true,因此带上了 CAPABILITY_IAM。#8071 修复的内容正是保证:当用户提供了自定义 IAM 角色(nodeRoleARN)时,也会为相应资源补齐 IAM capability 声明,避免 CloudFormation 因缺少能力声明而拒绝创建包含 IAM 资源的栈。

这一点与 capability(能力)模块的 IAM 角色栈设计一致——NewIAMRoleResourceSetForCapability 构建的 IAM 角色栈通过 roleNameCollector 把生成的角色 ARN 回写到 spec.RoleARN,其信任策略允许 capabilities.eks.amazonaws.com 服务主体执行 sts:AssumeRole / sts:TagSession。

延伸:capabilities 中自定义 IAM 角色的组合用法

修复背后的通用模式在 eksctl 的 capabilities(ACK / KRO / ARGOCD)功能中同样体现。以 examples/47-auto-mode-with-ack-kro-capabilities.yaml 为例:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: eks-capability-1
  region: ap-northeast-2

autoModeConfig:
  enabled: true

capabilities:
  # ACK - 使用已有角色(roleArn 注释掉了,默认由 eksctl 创建)
  - name: ack-capability
    type: ACK
    # roleArn: arn:aws:iam::123456789012:role/ACK-S3-Controller-Role
    deletePropagationPolicy: RETAIN
    attachPolicyARNs:
      - arn:aws:iam::aws:policy/AdministratorAccess
    tags:
      Environment: dev
      Team: platform

  # KRO - 角色由 eksctl 自动创建
  - name: kro-capability
    type: KRO
    deletePropagationPolicy: RETAIN
    accessPolicies:
      - policyARN: arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy
        accessScope:
          type: cluster

在 pkg/actions/capability/creator.go 的 CreateTasks 中可以看到决定性的分支:

// Only create IAM role stack if RoleARN is not provided
if cap.RoleARN == "" {
    if err := c.createIAMRoleStack(ctx, &cap); err != nil {
        return err
    }
}
return c.createCapability(ctx, &cap)

也就是说:提供了 roleArn 就直接复用;未提供才由 eksctl 创建 IAM 角色栈(栈名格式 eksctl-<cluster>-capability-role-<hash>,由 MakeIAMRoleStackName 基于 capability 名称的 SHA-1 哈希生成)。删除时,Remover.DeleteTasks 会并行删除 capability 栈与其 IAM 角色栈;栈的关联通过两个标签识别:

  • alpha.eksctl.io/capability-name(见 types.go)
  • alpha.eksctl.io/iam-role-for-capability

ARGOCD 类型的强制约束

若选用 ARGOCD 类型,Capability.Validate 要求必须提供 configuration.argocd.awsIdc 等完整配置,示例见 examples/48-auto-mode-with-argocd-capabilities.yaml。这里同样支持通过 roleArn 指定自定义角色,或在 attachPolicyARNs / attachPolicy 中提供策略后由 eksctl 创建角色。

实操:升级与验证建议

  • 升级路径:从旧版本升级到 v0.197.0 后,若此前因「提供自定义 nodeRoleARN 导致 CloudFormation 栈创建/更新失败」,可重新执行启用 Auto Mode 的配置,补齐后的 IAM capability 声明会生效。
  • 验证方式:启用 Auto Mode 后可执行 eksctl get capability --name <capability-name>(实现见 pkg/ctl/get/capability.go),查看 capability 的 STATUS 与 VERSION 是否进入 ACTIVE 状态。
  • 版本配套:本文描述的配置与行为以当前仓库(含 v0.197.0 之后演进)为准;autoModeConfig 字段、capabilities 块及 --enable-auto-mode(见 pkg/ctl/create/cluster.go)均为 eksctl v1alpha5 API 的标准入口。

小结

v0.197.0 虽然只包含一个 Bug 修复与一次文档清理,但它修复的边界条件颇具代表性:在「用户自带 IAM 角色」这一多云厂商场景常见的模式下,确保 CloudFormation 栈能力声明与角色来源保持一致。从配置校验(auto_mode.go)到运行时分支(auto_mode_updater.go),再到能力声明(cfn/manager/api.go、cfn/builder/auto_mode.go),整条链路为自定义角色与 eksctl 托管资源之间的协同提供了完整参考;同版本对 Hybrid Nodes 文档的清理(见 0.195.0 至 0.226.0 的持续迭代)则表明该功能文档仍在持续完善中。

登录后查看全文
eksctl