eksctl 0.197.0 解析:Auto Mode 自定义 IAM 角色的能力补齐与 Hybrid Nodes 文档清理
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 的持续迭代)则表明该功能文档仍在持续完善中。