eksctl 配置 EKS Hybrid Nodes:remoteNetworkConfig 网络与凭证实战指南
eksctl 配置 EKS Hybrid Nodes:remoteNetworkConfig 网络与凭证实战指南
EKS Hybrid Nodes 是 Amazon EKS 推出的新特性,允许你在自建本地与边缘基础设施上运行容器工作负载,并复用同一套 EKS 集群、特性与工具。本文围绕 eksctl 为此引入的顶层配置字段 remoteNetworkConfig,完整讲解如何在配置文件里打通「网络」与「凭证」两大核心环节,并结合仓库源码剖析 eksctl 在背后自动创建的安全组规则、路由、网关挂载、IAM 角色与 Access Entry,帮助你从「会写配置」进阶到「理解原理」。
EKS Hybrid Nodes 与 remoteNetworkConfig 概述
AWS EKS Hybrid Nodes 将 AWS 托管的 Kubernetes 体验延伸到本地环境,让用户能够以统一、标准化的方式在本地(on-premises)、边缘(edge)与云端(cloud)之间运行应用。它使用与云端 EKS 集群完全相同的集群、特性与工具,从而简化多云与混合云运维。
为了支持该特性,eksctl 在 ClusterConfig 中新增了一个顶层字段 remoteNetworkConfig。所有与 Hybrid Nodes 相关的配置都必须通过该字段(作为配置文件的一部分)来设置——没有对应的 CLI 旗标(flag)。这意味着:
- 新建集群时,在配置文件中写好
remoteNetworkConfig再执行eksctl create cluster -f config.yaml; - 对已存在的集群启用或更新 Hybrid Nodes,只需在配置文件中加入
remoteNetworkConfig后执行eksctl upgrade cluster。
remoteNetworkConfig 段承载了两大核心配置领域:networking(网络) 与 credentials(凭证)。下文逐一展开。
网络配置:打通 VPC 与本地网络
连接方式选择
EKS Hybrid Nodes 对"如何将本地网络接入 AWS VPC"保持灵活态度,支持多种官方推荐的连接方案,包括 AWS Site-to-Site VPN 与 AWS Direct Connect 等,你可以按实际场景选择最合适的一种。在多数方案中,你的 VPC 会被挂接到一个虚拟私有网关(VGW,Virtual Private Gateway) 或中转网关(TGW,Transit Gateway) 上。
eksctl 自动完成的三件事
如果你依赖 eksctl 创建 VPC,eksctl 还会在 VPC 范围内自动配置以下网络前置条件,以便 EKS 控制平面与远端节点通信:
- 入口/出口安全组规则(ingress/egress SG rules):从远端网络 CIDR 放行到控制平面的流量;
- 私有子网路由表中的路由(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"]
各字段含义:
| 字段 | 说明 |
|---|---|
remoteNetworkConfig.vpcGatewayID |
要挂接到 VPC 的网关 ID,必须是 VGW(vgw-*)或 TGW(tgw-*),用于承载 VPC 与远端网络之间的流量 |
remoteNetworkConfig.remoteNodeNetworks |
远端节点网络 CIDR 列表,eksctl 会据此创建安全组规则、路由与网关挂接,打通远端节点到控制平面的通信 |
remoteNetworkConfig.remotePodNetworks |
远端 Pod 网络 CIDR 列表,同样参与安全组与路由的自动化配置 |
仓库中对应的类型定义在 pkg/apis/eksctl.io/v1alpha5/types.go#L788-L798,RemoteNetworkConfig 结构体包含 iam、vpcGatewayID、remoteNodeNetworks、remotePodNetworks 四个字段;其中 VPCGateway 通过 tgw/vgw 前缀判断网关类型(见 types.go#L764-L786 的 IsTransitGateway() 与 IsVirtualPrivateGateway())。
不使用 TGW/VGW,或使用既有 VPC 的场景
如果你的连接方式不涉及 TGW 或 VGW,可以省略 remoteNetworkConfig.vpcGatewayID,或直接提供既有 VPC(vpc.id)。需要特别注意的是:
- 使用既有 VPC 时,eksctl 不会对其做任何改动,确保所有网络要求就绪的责任落在你身上;
- eksctl 只负责 VPC 内部的网络配置,不会搭建 VPC 外部的任何网络基础设施(即从 VGW/TGW 到远端网络之间的那一段,需要你自己解决)。
从源码看,addHybridNodesNetworking()(见 pkg/cfn/builder/vpc_ipv4.go#L381-L429)对两种网关分别处理:
- VGW 场景:创建
VirtualPrivateGatewayAttachment,并在每个可用区(AZ)的私有子网路由表中为每个远端网络 CIDR 添加指向VpnGatewayId的路由; - TGW 场景:创建
TransitGatewayAttachment(挂接到全部私有子网),再为每个私有子网路由表添加指向TransitGatewayId的路由; - 两者都没有:打印警告日志("a TGW or VGW was not provided for hybrid nodes connectivity, hence eksctl won't configure any related routes and gateway attachments for your VPC")并跳过,此时路由与网关挂接需要自行处理。
同时,在控制平面安全组层面,pkg/cfn/builder/cluster.go#L141-L151 会为 remoteNetworkConfig 中出现的所有 CIDR(节点 + Pod) 创建一条 SecurityGroupIngress 规则:IngressControlPlaneRemoteNetworksN,协议为 TCP、端口为 HTTPS(443),描述为 "Allow nodes/pods from remote network (x) to communicate to controlplane"。
凭证配置:SSM 与 IAM Roles Anywhere
凭证机制简介
EKS Hybrid Nodes 使用 AWS IAM Authenticator 配合临时 IAM 凭证来与 EKS 集群完成认证,临时凭证由以下两种服务之一提供:
- AWS SSM(AWS Systems Manager):默认方案;
- AWS IAM Roles Anywhere(IRA):基于 X.509 证书签发的临时凭证。
与自管理节点组(self-managed nodegroups)类似,如果你没有显式提供,eksctl 会为你创建一个 Hybrid Nodes IAM Role(供远端节点扮演)。
选择凭证提供者并配置
当使用 IAM Roles Anywhere 作为凭证提供者时,eksctl 会基于你提供的证书颁发机构捆绑包(iam.caBundleCert)自动创建 profile(配置文件) 和 trust anchor(信任锚):
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
字段约束(与校验逻辑一致,见 pkg/apis/eksctl.io/v1alpha5/validation.go#L157-L171):
iam.provider只支持SSM与IRA两个取值;从 0.203.0 版本起该字段大小写不敏感(见 docs/release_notes/0.203.0.md);iam.caBundleCert仅在 provider 为 IRA(IAM Roles Anywhere)时可以设置,SSM 模式下设置会报错;- provider 为 IRA 时
caBundleCert必填(它是信任锚的信任根)。
如果你不写 iam 段,eksctl 会在默认值处理阶段自动将 iam.provider 填充为 SSM(见 pkg/apis/eksctl.io/v1alpha5/defaults.go#L82-L89)。
获取 eksctl 创建的 ARN
eksctl 创建的 Hybrid Nodes Role 的 ARN,在后续将远端节点加入集群时需要用到:用于为 nodeadm 配置 NodeConfig,以及(使用 SSM 时)创建激活(activations)。获取方式:
aws cloudformation describe-stacks \
--stack-name eksctl-<CLUSTER_NAME>-cluster \
--query 'Stacks[].Outputs[?OutputKey==`RemoteNodesRoleARN`].[OutputValue]' \
--output text
同理,如果使用 IAM Roles Anywhere,可以用同样的命令获取 eksctl 创建的 trust anchor 与 anywhere profile 的 ARN,只需把 RemoteNodesRoleARN 分别替换为:
RemoteNodesTrustAnchorARN:信任锚 ARN;RemoteNodesAnywhereProfileARN:Anywhere Profile ARN。
这些输出项定义在 pkg/cfn/outputs/api.go#L38-L42。从源码看,SSM 场景输出 HybridNodesSSMRole 的 ARN(pkg/cfn/builder/iam.go#L206-L225),IRA 场景则依次输出信任锚、Profile 与 HybridNodesIRARole 的 ARN(iam.go#L194-L203)。
自备 IAM Role 的场景
如果你已有现成的 IAM Roles Anywhere 配置,或者使用 SSM,可以通过 remoteNetworkConfig.iam.roleARN 直接提供 Hybrid Nodes 使用的 IAM Role:
remoteNetworkConfig:
iam:
roleARN: arn:aws:iam::000011112222:role/HybridNodesRole
请注意:在此场景下,eksctl 不会为你创建 trust anchor 和 anywhere profile,这些 IAM Roles Anywhere 前置配置需要自行准备;eksctl 只会把该角色添加到 aws-auth ConfigMap 中(校验时也会打印相应警告,见 validation.go#L173-L176)。
源码视角:SSM 与 IRA 资源是如何构建的
eksctl 根据 iam.provider 选择不同的 CFN 资源构建路径(pkg/cfn/builder/iam.go#L227-L237):
- SSM 路径(
addSSM()):创建名为HybridNodesSSMRole的 IAM Role,AssumeRolePolicy 允许ssm.amazonaws.com扮演;内联策略包含ssm:DeregisterManagedInstance、ssm:DescribeInstanceInformation与eks:DescribeCluster,托管策略挂载AmazonSSMManagedInstanceCore与AmazonEC2ContainerRegistryPullOnly; - IRA 路径(
addIAMRolesAnywhere()):创建三件套——TrustAnchor:类型CERTIFICATE_BUNDLE,其X509CertificateData直接取自iam.caBundleCert;AnywhereProfile:名为remote-nodes,RoleArns指向 IRA Role,开启AcceptRoleSessionName;HybridNodesIRARole:AssumeRolePolicy 限定由IRA服务扮演,并附加aws:SourceArn指向信任锚的 ARN 条件,动作包含sts:TagSession、sts:SetSourceIdentity,策略内容与 SSM Role 类似(eks:DescribeCluster+ 两个托管策略)。
Access Entry:将角色映射为 Kubernetes 身份
为了让远端节点获得加入 EKS 集群的权限,eksctl 会创建一个 Access Entry:其 Principal ARN 为 Hybrid Nodes IAM Role,类型为 HYBRID_LINUX。例如:
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"
]
}
]
HYBRID_LINUX 类型定义在 pkg/apis/eksctl.io/v1alpha5/access_entry.go#L58-L59。在 CFN 构建器中(pkg/cfn/builder/cluster.go#L531-L549),addAccessEntryForRemoteNodes() 会根据 provider 选择 HybridNodesSSMRole 或 HybridNodesIRARole 作为 PrincipalArn,创建 RemoteNodesAccessEntry 资源,并设置 AWSCloudFormationDependsOn: ["ControlPlane"] 确保控制平面就绪后再挂接。
校验规则一览:哪些写法会被拒绝
仓库在 pkg/apis/eksctl.io/v1alpha5/validation.go#L104-L179 的 validateRemoteNetworkingConfig() 中集中校验 remoteNetworkConfig,以下写法会被直接拒绝或告警:
| 场景 | 结果 |
|---|---|
Outposts 集群未设置 outpost.etcdInstanceType |
报错:remoteNetworkConfig on Outpost clusters requires outpost.etcdInstanceType to be set |
| 集群启用 IPv6 地址族 | 报错:remoteNetworkConfig is not supported on EKS cluster configured with IPv6 address family |
authenticationMode 为 CONFIG_MAP |
报错:要求 API_AND_CONFIG_MAP 或 API 模式 |
remoteNodeNetworks 超过 1 个 |
报错:每个列表只允许一个网络 |
remotePodNetworks 超过 1 个 |
报错:每个列表只允许一个网络 |
remoteNodeNetworks 为空且非 Outposts |
报错:remoteNetworkConfig.remoteNodeNetworks must be set and non-empty(创建时);若两列表均为显式空,则视为"升级时移除所有远端网络"或"创建时忽略",并打印警告 |
使用既有 VPC 又设置 vpcGatewayID |
报错:remoteNetworkConfig.vpcGatewayID is not supported when using pre-existing VPC |
vpcGatewayID 不是 tgw-*/vgw-* |
报错:仅支持中转网关或虚拟私有网关 |
iam.provider 非法 |
报错:仅支持 ssm 与 ira |
SSM 模式设置 caBundleCert |
报错:SSM 不支持该字段 |
IRA 模式未设置 caBundleCert |
报错:必填 |
设置 iam.roleARN |
仅警告:eksctl 只添加 aws-auth 条目,不搭建 SSM/IRA 配套配置 |
这些校验与类型定义共同保证了配置在提交给 CloudFormation / EKS API 之前就是合法、自洽的。
对既有集群的更新:eksctl upgrade cluster
对已存在的集群启用或调整 Hybrid Nodes 配置,把 remoteNetworkConfig 写入配置文件后执行 eksctl upgrade cluster --config-file config.yaml。底层调用链位于 pkg/actions/cluster/owned.go#L60-L123:Upgrade() 在完成版本升级后调用 updateRemoteNetworkConfig(),后者将配置中的 RemoteNodeNetworks/RemotePodNetworks CIDR 组装成 eks.RemoteNetworkConfigRequest,调用 EKS 的 UpdateClusterConfig API(接口声明见 pkg/awsapi/eks.go#L500)。
值得注意的细节:
- 若 EKS 返回 "No changes detected" 错误,eksctl 会打印 "remote network config is already up-to-date" 并以成功路径返回(不视为失败);
- 支持 dry-run(
--dry-run),此时只打印将要执行的动作而不真正调用 API; - 对应的行为测试覆盖在 pkg/actions/cluster/remote_network_config_test.go:包括
remoteNetworkConfig为 nil 时跳过、节点与 Pod 网络 CIDR 正确传递、显式空列表(移除全部远端网络)时请求体仍非 nil、无变更时的幂等处理等场景。
另外,新建集群时 remoteNetworkConfig 会被映射进 EKS 集群资源的 RemoteNetworkConfig(见 pkg/cfn/builder/cluster.go#L476-L488),并在自定义资源路径下透传(见 pkg/cfn/builder/beta.go#L87-L89)。
Add-ons 支持:CNI 选型与注意事项
容器网络接口(CNI)方面需要特别注意:
- AWS VPC CNI 不能用于 hybrid nodes;
- Cilium 与 Calico 的核心能力受支持,可用于 hybrid nodes;
- 你可以用 Helm 等任何顺手的工具来管理所选 CNI。
另一个容易踩的坑:如果集群内为自管理节点组或 EKS 托管节点组安装了 VPC CNI,必须使用 v1.19.0-eksbuild.1 或更高版本——该版本对 add-on 的 DaemonSet 做了更新,将 hybrid nodes 排除在安装范围之外,避免 VPC CNI 被误装到远端节点上。
参考示例与进一步阅读
仓库提供了可直接参考的最小示例 examples/43-hybrid-nodes.yaml,展示了完整骨架(apiVersion、kind、metadata、region、version 与 remoteNetworkConfig 段,默认使用 SSM provider):
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"]
官方 ClusterConfig 的 JSON Schema 中也登记了 remoteNetworkConfig 字段(见 pkg/apis/eksctl.io/v1alpha5/assets/schema.json#L779-L781),编辑器可据此获得自动补全与校验。
结合本文的配置示例与源码分析,你可以从零搭建 Hybrid Nodes 集群,或为既有集群无缝启用远端节点——网络侧只需声明 CIDR 与网关,凭证侧只需声明 provider 与证书,其余基础设施与权限编排全部交给 eksctl 在 CloudFormation 模板中自动完成。