eksctl 0.195.0 新特性实战指南:EKS Auto Mode 与 Hybrid Nodes 支持
eksctl 0.195.0 新特性实战指南:EKS Auto Mode 与 Hybrid Nodes 支持
导读
本指南围绕 eksctl v0.195.0 的两项核心新特性展开:EKS Auto Mode(将计算、存储与网络组件交给 AWS 全托管)与 EKS Hybrid Nodes(让本地与边缘节点加入 EKS 集群)。文章完整讲解 autoModeConfig 与 remoteNetworkConfig 两个配置字段的语法、参数语义与校验规则,给出可直接复用的配置文件与命令,并深入到仓库源码层解释 eksctl 是如何调用 EKS API、创建 IAM 资源与 Access Entry 的。读完本文,你将掌握如何用 eksctl 一键创建 Auto Mode 集群、在已有集群上启用/禁用 Auto Mode,以及如何通过配置文件接入 Hybrid Nodes 的联网与凭证体系。
版本说明:文中所有命令、参数与行为均以当前仓库(eksctl 0.195.0)的实现为准;示例配置可直接对照 examples/42-auto-mode.yaml 与 examples/43-hybrid-nodes.yaml 使用。
一、版本概览:0.195.0 带来了什么
根据 docs/release_notes/0.195.0.md 的发布说明,v0.195.0 的主要变更如下:
- 🚀 Features(新特性)
- 支持 EKS Auto Mode(对应 issue/PR #8058)
- 新增对 EKS Hybrid Nodes 的支持(对应 #8062)
- 🧰 Maintenance(维护项)
- 移除创建集群时对
aws-efs-csi-driver的删除逻辑(#8045) - 修复 addons 集成测试(#8042)
- 移除创建集群时对
其中,前两项是版本的核心亮点:它们分别引入/完善了两种重要的 EKS 部署形态。而在维护项中,关于 aws-efs-csi-driver 的改动可以从 pkg/actions/addon/addon.go 处的注释得到印证——该文件描述了“当集群没有 nodegroup 时,无需等待 coredns、aws-ebs-csi-driver 或 aws-efs-csi-driver”的行为逻辑,说明 0.195.0 正在逐步收敛默认 addon 的清理策略。
二、EKS Auto Mode:把数据平面交给 AWS
2.1 什么是 EKS Auto Mode
EKS Auto Mode 将 AWS 对 Kubernetes 集群的托管范围从“控制平面”扩展到“支撑工作负载运行的基础设施”。启用后,AWS 会代为搭建并管理计算、网络与存储相关的数据平面组件,并将许多 Kubernetes 能力作为核心组件(core components)而非 addon 提供,典型包括:
- 计算自动扩缩容(compute autoscaling)
- Pod 与服务网络(pod and service networking)
- 应用负载均衡(application load balancing)
- 集群 DNS
- 块存储(block storage)
- GPU 支持
这使得你可以把日常运维中的关键基础设施决策委托给 AWS,借助其托管经验来保障集群的平稳运行。对应地,eksctl 引入了一个新的顶层字段 autoModeConfig 用于开启与配置该功能。
2.2 autoModeConfig 配置字段详解
autoModeConfig 是本次新增的顶层配置字段,其完整结构定义在 pkg/apis/eksctl.io/v1alpha5/auto_mode.go 中,包含四个字段:
autoModeConfig:
# defaults to false
enabled: boolean
# optional, defaults to [general-purpose, system].
# To disable creation of nodePools, set it to the empty array ([]).
nodePools: []string
# optional, eksctl creates a new role if this is not supplied
# and nodePools are present.
nodeRoleARN: string
各字段语义如下:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled |
boolean | false |
是否启用 Auto Mode |
nodePools |
[]string | ["general-purpose", "system"] |
要创建的 Node Pool 列表;设为空数组 [] 可禁止创建默认 Node Pool |
nodeRoleARN |
string(ARN) | 空 | Auto Mode 启动的节点使用的 IAM 角色 ARN;未提供且配置了 nodePools 时,eksctl 会自动创建该角色 |
permissionsBoundaryARN |
string(ARN) | 空 | 创建 Auto Mode 节点角色时附加的 Permissions Boundary(源码字段,见 auto_mode.go) |
其中 Node Pool 的合法取值只有两个:general-purpose 与 system。这一点在源码中通过常量 AutoModeNodePoolGeneralPurpose 与 AutoModeNodePoolSystem 明确限定,见 pkg/apis/eksctl.io/v1alpha5/auto_mode.go。如果你没有显式配置 nodePools,pkg/apis/eksctl.io/v1alpha5/defaults.go 中的默认值逻辑会把这两个已知 Node Pool 自动填充进去。
2.3 创建启用 Auto Mode 的集群
创建集群只需把 autoModeConfig.enabled 设为 true,然后照常使用 eksctl create cluster:
# auto-mode-cluster.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: auto-mode-cluster
region: us-west-2
autoModeConfig:
enabled: true
$ eksctl create cluster -f auto-mode-cluster.yaml
当 autoModeConfig.enabled 为 true 时,eksctl 在调用 EKS API 创建集群时会同时传递:
computeConfig.enabled: truekubernetesNetworkConfig.elasticLoadBalancing.enabled: truestorageConfig.blockStorage.enabled: true
从而开启对计算、存储、网络等数据平面组件的托管。这一步可以直接在上游 Updater.enableAutoMode 的 UpdateClusterConfigInput 构造中看到——它会同时设置 ComputeConfig、ElasticLoadBalancing 与 BlockStorage 三个开关,见 pkg/actions/automode/auto_mode_updater.go。
此外,eksctl 会自动创建一个供 Auto Mode 节点使用的 IAM 角色(Node Role),并创建 general-purpose 与 system 两个 Node Pool。角色创建由 RoleManager.CreateOrImport 完成,日志会输出 creating node role for Auto Mode,对应源码 pkg/actions/automode/auto_mode_updater.go。
自定义 Node Pool(典型场景:指定不同的子网集):如果不想使用默认的 Node Pool,例如要配置使用不同子网集的 Node Pool,可将 nodePools 置为空数组,eksctl 便不会创建默认 Node Pool:
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: auto-mode-cluster
region: us-west-2
autoModeConfig:
enabled: true
nodePools: [] # disables creation of default node pools.
2.4 在已有集群上启用 / 更新 Auto Mode
对现有集群启用 Auto Mode,只需在配置文件中声明 autoModeConfig.enabled: true 并执行专门的更新命令:
# cluster.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: cluster
region: us-west-2
autoModeConfig:
enabled: true
$ eksctl update auto-mode-config -f cluster.yaml
eksctl update auto-mode-config 子命令的实现位于 pkg/ctl/update/auto_mode_config.go,它提供以下额外参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
--drain-all-nodegroups |
false |
启用 Auto Mode 后排空现有 nodegroup,使已有工作负载迁移到 Auto Mode 管理的节点上 |
--drain-parallel |
1 |
并行排空的节点数 |
--ignore-missing-subnets |
false |
集群 CloudFormation 栈中若包含已不存在的子网,eksctl 默认会报错;指定该参数可抑制错误 |
--timeout |
40m |
更新等待超时时间(默认 40 分钟) |
在更新流程中,Updater.Update(见 pkg/actions/automode/auto_mode_updater.go)会做几件事:
- 幂等判断:若集群已启用 Auto Mode,且
nodePools与当前集群配置一致,则直接提示Auto Mode is already enabled and up-to-date并返回; - 不可变约束:
autoModeConfig.nodeRoleARN一旦设置便不可修改,若检测到试图变更会直接报错autoModeConfig.nodeRoleARN cannot be modified; - 启用前置检查:
preflightCheck会检查kube-system与karpenter命名空间中是否存在 Karpenter Pod,若存在则要求先删除或缩容到 0(见 auto_mode_updater.go); - 角色与集群角色更新:通过
ClusterRoleManager.UpdateRoleForAutoMode为集群角色补充 Auto Mode 所需策略,必要时创建节点角色; - 调用 EKS 更新 API 并等待更新完成(超时 30 分钟,见 auto_mode_updater.go);
- 如果指定了
--drain-all-nodegroups,排空现有 nodegroup; - 完成后提示:核心网络 addon(VPC-CNI、CoreDNS、kube-proxy 等)已不再需要,可用
eksctl delete addon删除。
注意事项:如果集群由 eksctl 创建且使用公有子网作为集群子网,Auto Mode 会在公有子网中启动节点。若希望 Auto Mode 启动的工作节点使用私有子网,需要先更新集群配置以使用私有子网(参考 cluster-subnets-security-groups.md 的用法说明)。
2.5 禁用 Auto Mode
禁用 Auto Mode 同样通过 eksctl update auto-mode-config 完成,只需把 enabled 设为 false:
# cluster.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: auto-mode-cluster
region: us-west-2
autoModeConfig:
enabled: false
$ eksctl update auto-mode-config -f cluster.yaml
从源码看,禁用流程(disableAutoMode,见 auto_mode_updater.go)会:
- 将
computeConfig.enabled、elasticLoadBalancing.enabled、blockStorage.enabled全部置为false; - 通过
RoleManager.DeleteIfRequired清理 Auto Mode 相关的 IAM 资源; - 通过
ClusterRoleManager.DeleteAutoModePolicies从集群角色中移除 Auto Mode 策略。
若集群本来就未启用 Auto Mode,命令会提示 Auto Mode is already disabled 并直接返回。
2.6 Auto Mode 配置的校验规则(源码级)
Auto Mode 配置并非随意组合,pkg/apis/eksctl.io/v1alpha5/auto_mode.go 中的 ValidateAutoModeConfig 明确定义了以下约束,这些约束也被 auto_mode_validation_test.go 的测试用例覆盖:
- Auto Mode 不支持 Outposts 集群;
nodePools为空数组时,不允许同时指定nodeRoleARN或permissionsBoundaryARN;- 同时指定
nodeRoleARN与permissionsBoundaryARN是非法的(二者互斥); nodePools中出现重复值会报错found duplicate node pool;nodePools中出现未知取值会报错invalid NodePool;- Auto Mode 未启用(
enabled: false)时,不允许设置nodeRoleARN、permissionsBoundaryARN或非空nodePools。
此外,pkg/apis/eksctl.io/v1alpha5/types.go 中的 IsAutoModeEnabled 帮助方法用于判断集群是否启用了 Auto Mode,整个校验流程在 pkg/apis/eksctl.io/v1alpha5/validation.go 中被统一接入集群配置的整体校验。
行为变更预告(重要):根据 userdocs/src/usage/auto-mode.md 的说明,在 eksctl 后续版本中 Auto Mode 将默认启用,届时创建集群将不再默认创建托管节点组。若你希望保持当前行为(默认创建托管节点组以及 VPC-CNI、CoreDNS、kube-proxy 等网络 addon),必须在集群配置中显式声明
autoModeConfig.enabled: false。此变更影响所有未显式书写autoModeConfig的集群创建。
三、EKS Hybrid Nodes:把本地与边缘节点纳入 EKS 集群
3.1 什么是 Hybrid Nodes
EKS Hybrid Nodes 是 AWS EKS 的一项新特性,允许你在客户自管的基础设施上运行本地(on-premises)与边缘(edge)应用,同时使用与 AWS 云端一致的 EKS 集群、特性与工具。它把 AWS 托管的 Kubernetes 体验带到本地环境,帮助用户在不同地点(本地、边缘、云)之间简化并标准化应用的运行方式。
为支持该特性,eksctl 引入了新的顶层字段 remoteNetworkConfig。与 Auto Mode 不同,所有 Hybrid Nodes 相关配置都通过配置文件完成,没有对应的 CLI flag。你可以在创建集群时配置它,也可以在已有集群上通过修改配置文件并执行 eksctl upgrade cluster 来启用或更新 Hybrid Nodes 配置。
remoteNetworkConfig 负责两大核心领域:网络(networking) 与 凭证(credentials),其结构定义在 pkg/apis/eksctl.io/v1alpha5/types.go 中。
3.2 网络配置:连通本地网络与 AWS VPC
EKS Hybrid Nodes 对“如何把本地网络连到 AWS VPC”持开放态度,常见的连接方式包括 AWS Site-to-Site VPN 与 AWS Direct Connect。在大多数方案中,你的 VPC 会附着到一个**虚拟私有网关(VGW)或中转网关(TGW)**上。
如果依赖 eksctl 创建 VPC,eksctl 会在 VPC 范围内自动完成以下网络前置条件的配置(见 userdocs/src/usage/hybrid-nodes.md 的说明):
- 出入方向的安全组规则(ingress/egress SG rules)
- 私有子网路由表中的路由(routes in the private subnets' route tables)
- VPC 到指定 TGW/VGW 的网关附着(VPC gateway attachment)
示例配置:
remoteNetworkConfig:
vpcGatewayID: tgw-xxxx # either VGW or TGW to be attached to your VPC
remoteNodeNetworks:
# eksctl will create, behind the scenes, SG rules, routes, and a VPC gateway attachment,
# to facilitate communication between remote network(s) and EKS control plane, via the attached gateway
- cidrs: ["10.80.146.0/24"]
remotePodNetworks:
- cidrs: ["10.86.30.0/23"]
要点说明:
vpcGatewayID:VGW 或 TGW 的 ID。仅当使用 eksctl 新建的 VPC 时才允许设置——如果使用预先存在的 VPC,设置它会报错(见下文校验规则),且 eksctl 不会对既有 VPC 做任何改动,所有网络要求都需你自己保证;remoteNodeNetworks:远程节点网络的 CIDR 列表;remotePodNetworks:远程 Pod 网络的 CIDR 列表。
如果所选连接方式不涉及 TGW/VGW,则可以省略 vpcGatewayID,或直接提供预先存在的 VPC。需要注意:eksctl 不会在 AWS VPC 之外搭建任何网络基础设施(即从 VGW/TGW 到远端网络的部分不在其职责范围内)。
3.3 凭证配置:SSM 与 IAM Roles Anywhere
Hybrid Nodes 使用 AWS IAM Authenticator 与临时 IAM 凭证来认证接入集群,凭证由 AWS SSM 或 AWS IAM Roles Anywhere 两种服务之一提供。与自管节点组类似,如果未另行提供,eksctl 会为 Hybrid Nodes 创建一个可被远程节点扮演的 IAM 角色。
- 使用 SSM(默认):eksctl 默认的凭证提供方就是 SSM,相关默认值逻辑在 pkg/apis/eksctl.io/v1alpha5/defaults.go 中:当未指定 provider 时自动填充为
SSMProvider; - 使用 IAM Roles Anywhere(IRA):此时 eksctl 会基于你提供的 CA 证书包(
iam.caBundleCert)创建 Profile 与 Trust Anchor,作为验证节点 X.509 证书的信任根:
remoteNetworkConfig:
iam:
# the provider for temporary IAM credentials. Default is SSM.
provider: IRA
# the certificate authority bundle that serves as the root of trust,
# used to validate the X.509 certificates provided by your nodes.
# can only be set when provider is IAMRolesAnywhere.
caBundleCert: xxxx
iam 子字段(定义见 types.go)完整参数如下:
| 字段 | 可选值 | 说明 |
|---|---|---|
provider |
SSM(默认)、IRA |
为远程节点提供 IAM 凭证的 AWS 服务;若选 IRA,eksctl 会在后台创建所需的 Trust Anchor 与 Anywhere Profile |
roleARN |
IAM 角色 ARN | 添加到 aws-auth configmap 中供远程节点使用的角色;未设置时 eksctl 自动创建角色并完成 SSM/IRA 配置 |
caBundleCert |
证书内容 | IRA Trust Anchor 使用的 CA 证书包;仅当 provider 为 IRA 时可设置,且此时为必填 |
获取 eksctl 创建的角色 ARN:加入远程节点时(配置 nodeadm 的 NodeConfig、使用 SSM 时创建 activation)需要用到 Hybrid Nodes 角色 ARN,可通过 CloudFormation 输出查询:
aws cloudformation describe-stacks \
--stack-name eksctl-<CLUSTER_NAME>-cluster \
--query 'Stacks[].Outputs[?OutputKey==`RemoteNodesRoleARN`].[OutputValue]' \
--output text
类似地,如果使用 IAM Roles Anywhere,可用同样的命令把 RemoteNodesRoleARN 替换为 RemoteNodesTrustAnchorARN 或 RemoteNodesAnywhereProfileARN 来获取 Trust Anchor 与 Anywhere Profile 的 ARN。这些 CloudFormation 输出定义在 pkg/cfn/builder/iam.go 中,即:IRA 场景下同时输出 RemoteNodesTrustAnchorARN、RemoteNodesAnywhereProfileARN 与 RemoteNodesRoleARN,SSM 场景下输出 RemoteNodesRoleARN。
使用既有 IAM 角色:如果你已有现成的 IAM Roles Anywhere 配置,或使用 SSM 作为 provider,可通过 remoteNetworkConfig.iam.roleARN 提供角色。注意在此场景下,eksctl 不会为你创建 Trust Anchor 与 Anywhere Profile:
remoteNetworkConfig:
iam:
roleARN: arn:aws:iam::000011112222:role/HybridNodesRole
当设置了 roleARN 时,eksctl 只会向 aws-auth configmap 添加对应条目,而创建所需 SSM/IRA 配置的责任则落在用户身上(源码在 validation.go 中以警告日志形式提示了这一点)。
3.4 将角色映射为 Kubernetes 身份(Access Entry)
为把 Hybrid Nodes 角色映射为 Kubernetes 身份、授权远程节点加入集群,eksctl 会创建一个以 Hybrid Nodes IAM 角色为 principal ARN、类型为 HYBRID_LINUX 的 Access Entry。该类型定义在 pkg/apis/eksctl.io/v1alpha5/access_entry.go,并会关联 Kubernetes 组 system:nodes:
eksctl get accessentry --cluster my-cluster --principal-arn arn:aws:iam::000011112222:role/eksctl-my-cluster-clust-HybridNodesSSMRole-XiIAg0d29PkO --output json
[
{
"principalARN": "arn:aws:iam::000011112222:role/eksctl-my-cluster-clust-HybridNodesSSMRole-XiIAg0d29PkO",
"kubernetesGroups": [
"system:nodes"
]
}
]
3.5 remoteNetworkConfig 校验规则(源码级)
validation.go 中的 validateRemoteNetworkingConfig 定义了一系列约束,值得在配置前了解:
- Outposts 集群:配置
remoteNetworkConfig时,Outpost 集群必须设置outpost.etcdInstanceType; - IPv6 集群不支持:配置了 IPv6 地址族的集群不能使用
remoteNetworkConfig; - 认证模式要求:
remoteNetworkConfig要求集群的authenticationMode为API_AND_CONFIG_MAP或API,不能是CONFIG_MAP; - 网络数量限制:
remoteNodeNetworks与remotePodNetworks各最多只能配置一个; - 网关约束:
vpcGatewayID必须是tgw-*(中转网关)或vgw-*(虚拟私有网关)格式,且不能与预先存在的 VPC 同时使用; - 凭证约束:
iam.provider只能是SSM或IRA;provider 为 SSM 时不能设置caBundleCert;provider 为 IRA 时caBundleCert为必填。
这些约束在 validation_test.go 与 outposts_validation_test.go 中均有对应的测试用例覆盖。
3.6 一个完整的 Hybrid Nodes 配置示例
仓库自带的 examples/43-hybrid-nodes.yaml 给出了一个可直接套用的完整示例(已省略可选的 vpcGatewayID 与 caBundleCert):
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: hybrid-2
region: us-west-2
version: "1.31"
remoteNetworkConfig:
iam:
provider: SSM
# caBundleCert: ceva
# vpcGatewayID: tgw-028fbe2348e6eed74
remoteNodeNetworks:
- cidrs: ["10.80.146.0/24"]
3.7 关于 CNI 的重要说明
容器网络接口(CNI)方面,AWS VPC CNI 不能用于 Hybrid Nodes;支持用于 Hybrid Nodes 的核心 CNI 能力是 Cilium 与 Calico,你可以用 Helm 等工具自行管理 CNI 的安装。
此外有一个版本相关的坑需要注意:如果集群中为自管或 EKS 托管节点组安装了 VPC CNI,必须使用 v1.19.0-eksbuild.1 或更高版本,该版本对 addon 的 DaemonSet 做了更新,将其排除在 Hybrid Nodes 上安装的范围之外。
四、补充:示例文件与延伸阅读
- Auto Mode 配置示例:examples/42-auto-mode.yaml —— 注释清晰展示了
enabled、nodePools、nodeRoleARN三个字段的默认值与可选性; - Hybrid Nodes 配置示例:examples/43-hybrid-nodes.yaml;
- 官方用户文档:userdocs/src/usage/auto-mode.md 与 userdocs/src/usage/hybrid-nodes.md,其中包含更完整的背景说明与行为变更预告;
- 相关配置文件参考:
autoModeConfig与remoteNetworkConfig的完整 JSON Schema 见 pkg/apis/eksctl.io/v1alpha5/assets/schema.json(AutoModeConfig与RemoteNetworkConfig两个 definition),schema 的字段描述可作为 IDE 补全与校验的权威依据。
五、总结
eksctl 0.195.0 通过两个新的顶层配置字段,把两种重要的 EKS 部署形态纳入了 CLI 的一键管理:
- Auto Mode(
autoModeConfig):以computeConfig、elasticLoadBalancing、blockStorage三个开关的联动为核心,配合自动创建节点角色与默认 Node Pool,让 AWS 托管从控制平面延伸到数据平面;创建、更新、禁用分别对应eksctl create cluster与eksctl update auto-mode-config两个命令。 - Hybrid Nodes(
remoteNetworkConfig):以网络(VPC 网关附着、路由、安全组)与凭证(SSM / IAM Roles Anywhere、角色创建、Access Entry)两条主线,把本地节点安全地接入 EKS 集群。
两者的共同特点是“配置即声明、后台自动化”:绝大多数基础设施细节(角色、信任锚、网关附着、Access Entry)都由 eksctl 在后台自动创建,用户只需在配置文件中表达意图。同时,源码中严格的校验逻辑(Node Pool 取值、provider 与 caBundleCert 的搭配、网关 ID 格式、认证模式要求等)保证了错误配置会被尽早拦截。在使用时请特别留意 Auto Mode 即将默认启用、VPC CNI 版本下限(v1.19.0-eksbuild.1)等版本相关事项。