使用 eksctl 自定义 kubelet 配置:kubeletExtraConfig 详解与节点资源预留实践
使用 eksctl 自定义 kubelet 配置:kubeletExtraConfig 详解与节点资源预留实践
本指南讲解 eksctl 中自定义 kubelet 配置的核心能力:通过集群配置文件中的 kubeletExtraConfig 字段,为节点 kubelet 注入自由格式的 kubelet 配置,实现系统资源预留(kubeReserved/systemReserved)、驱逐阈值(evictionHard)与特性开关(featureGates)的精细控制。读者将掌握 kubeletExtraConfig 的完整语法、字段约束与默认值覆盖规则,理解混合实例节点组下资源预留的计算策略,并学会如何避免因错误配置导致节点进入 NotReady 状态。
为什么需要自定义 kubelet 配置
Kubernetes 节点的可调度资源(Allocatable)等于节点总容量减去 kubelet 与系统守护进程预留的资源。如果不对这些资源做预留,在资源紧张时 kubelet 可能因自身无法获得足够的 CPU 或内存而无法驱逐 Pod,最终导致节点进入 NotReady 状态。eksctl 通过 kubeletExtraConfig 字段将这份控制权交给用户:配置文件中写入的自由格式 YAML 会被嵌入到最终的 kubelet.yaml 中,从而直接影响节点的资源预留与驱逐行为。
在 eksctl 的 API 类型定义中,KubeletExtraConfig 被声明为 InlineDocument(任意 JSON/YAML 文档),并明确注释为"Customize kubelet config",见 pkg/apis/eksctl.io/v1alpha5/types.go:
// Customize `kubelet` config
// +optional
KubeletExtraConfig *InlineDocument `json:"kubeletExtraConfig,omitempty"`
该字段位于 unmanaged(自管理)节点组(nodeGroups)下,属于 NodeGroup 结构体。与托管节点组(managedNodeGroups)不同,自管理节点组直接通过 userdata 引导 kubelet,因此可以承载这类自定义配置。
kubeletExtraConfig 的完整示例
以下配置创建一个节点组,为 kubelet 预留 300m vCPU、300Mi 内存与 1Gi 临时存储,为操作系统守护进程预留同样大小的一组资源,并在可用内存低于 200Mi 或根文件系统剩余不足 10% 时触发 Pod 驱逐:
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: dev-cluster-1
region: eu-north-1
nodeGroups:
- name: ng-1
instanceType: m5a.xlarge
desiredCapacity: 1
kubeletExtraConfig:
kubeReserved:
cpu: "300m"
memory: "300Mi"
ephemeral-storage: "1Gi"
kubeReservedCgroup: "/kube-reserved"
systemReserved:
cpu: "300m"
memory: "300Mi"
ephemeral-storage: "1Gi"
evictionHard:
memory.available: "200Mi"
nodefs.available: "10%"
featureGates:
RotateKubeletServerCertificate: true # has to be enabled, otherwise it will be disabled
配置中各字段的含义如下:
| 字段 | 作用 | 示例取值 |
|---|---|---|
kubeReserved |
为 kubelet 自身预留的资源(CPU/内存/临时存储) | cpu: "300m"、memory: "300Mi"、ephemeral-storage: "1Gi" |
kubeReservedCgroup |
kubelet 预留资源对应的 cgroup 路径 | /kube-reserved |
systemReserved |
为系统守护进程(如 sshd、journald 等)预留的资源 | 与 kubeReserved 结构相同 |
evictionHard |
硬驱逐阈值,达到后立即驱逐 Pod | memory.available: "200Mi"、nodefs.available: "10%" |
featureGates |
kubelet 特性开关 | RotateKubeletServerCertificate: true |
理解资源量纲与驱逐含义
cpu使用 Kubernetes 资源量纲:300m表示 0.3 个 vCPU,1表示完整 vCPU。memory使用二进制量纲:300Mi表示 300 MiB(约 314.6 MB),1Gi表示 1 GiB。evictionHard是 kubelet 的硬性驱逐阈值:memory.available表示节点可用内存低于该值时开始驱逐,nodefs.available表示根文件系统剩余容量低于该百分比(如 10%)时开始驱逐。
字段约束:哪些 kubelet 配置不能覆盖
并非所有 kubelet 配置都可以通过 kubeletExtraConfig 覆盖。部分字段由 eksctl 自行设置,是集群正常工作的关键,不允许用户改写,包括:
addressclusterDomainauthenticationauthorizationserverTLSBootstrap
这一限制在源码校验逻辑中有明确实现,见 pkg/apis/eksctl.io/v1alpha5/validation.go:
var kubeletForbiddenFields = map[string]struct{}{
"kind": {},
"apiVersion": {},
"address": {},
"clusterDomain": {},
"authentication": {},
"authorization": {},
"serverTLSBootstrap": {},
}
for k := range *kubeletConfig {
if _, exists := kubeletForbiddenFields[k]; exists {
return fmt.Errorf("cannot override %q in kubelet config, as it's critical to eksctl functionality", k)
}
}
从源码可见,除了原文档列出的 5 个字段,kind 和 apiVersion 也在禁止列表中——它们用于标识 kubelet 配置的类型元数据,同样不能由用户改写。如果配置中包含了这些字段,eksctl 会在配置校验阶段直接报错 cannot override "<field>" in kubelet config, as it's critical to eksctl functionality,对应的测试用例见 pkg/apis/eksctl.io/v1alpha5/validation_test.go。
同时,校验还确认了允许的配置项(kubeReserved、kubeReservedCgroup、cgroupDriver、featureGates 等),见 validation_test.go,说明除上述禁止字段外的 kubelet 配置项均可自由使用。
AMI 家族限制
kubeletExtraConfig 并非适用于所有 AMI 家族。从节点校验逻辑(validation.go)可以看到:
- Windows 镜像:不支持
kubeletExtraConfig,设置后会报unsupported field错误; - Bottlerocket:不支持
kubeletExtraConfig,同时也不支持preBootstrapCommands和overrideBootstrapCommand(Bottlerocket 使用专门的bottlerocket.settings配置体系); - Amazon Linux 2、Amazon Linux 2023、Ubuntu:支持
kubeletExtraConfig。
默认值覆盖规则与资源预留计算
覆盖语义:整段替换而非合并
在示例配置中,给定 m5a.xlarge 实例(4 vCPU、16 GiB 内存),计算后的 Allocatable 约为 3.4 个 vCPU 和 15.4 GiB 内存。这里有一个关键语义需要牢记:kubeletExtraConfig 中指定的字段值会完整覆盖 eksctl 设置的默认值,而不是做增量合并。
缺省参数的"智能默认值"
尽管覆盖语义是整段替换,但如果你只省略 kubeReserved 中的部分参数(例如只写 cpu 而不写 memory、ephemeral-storage),被省略的参数会被自动补充为基于 AWS 实例类型计算的合理默认值。这保证了即使部分字段缺失,节点仍能获得合理的资源预留,不会因为配置不完整而导致调度异常。
混合实例节点组的 kubeReserved 计算
当节点组使用混合实例(通过 instancesDistribution 配置多种实例类型)时,kubeReserved 的计算遵循一条重要规则:
按
InstanceDistribution.InstanceTypes列表中最小规格的实例来计算资源预留。
这样做的原因是:如果按最大实例预留资源,最小实例会因为预留过多而几乎没有可调度资源。而按最小实例预留,则确保任何实例都不会因预留过大而无法调度 Pod。当然,这种策略的代价是对最大规格实例而言,预留可能偏小。
因此官方建议:配置混合实例节点组时,尽量选用 CPU 与内存规格一致的实例(如 m5a.large 与 m5.large、c5.2xlarge 与 m5.2xlarge 这类"同规格不同族"的组合),这样 kubeReserved 的单一计算结果对所有实例都合理;如果确实需要混用差异较大的规格,则要接受预留值对部分实例偏大或偏小的事实,并据此评估驱逐风险。
该能力在 eksctl 0.24.0 版本中正式加入("Added kubeReserved calculation support for mixed instance NodeGroups",见 docs/release_notes/0.24.0.md),而"按实例类型设置 kubeReserved 默认值"的能力则从 0.17.0 起引入(见 docs/release_notes/0.17.0.md)。
重要警告:featureGates 与 RotateKubeletServerCertificate
这是最容易踩坑的地方,务必注意:
默认情况下,eksctl 会设置
featureGates.RotateKubeletServerCertificate=true;但一旦你提供了自定义的featureGates,该设置就会被取消(unset)。
也就是说,只要你在 kubeletExtraConfig 中写入了任何 featureGates 内容,RotateKubeletServerCertificate 就不再被自动启用。而该特性关系到 kubelet 服务端证书的自动轮换,关闭后证书过期可能导致节点失联。
因此官方给出明确建议:除非你有必须禁用的理由,否则在任何自定义 featureGates 中都要显式包含 RotateKubeletServerCertificate: true(正如示例配置所示,这一行还带有注释提醒)。kubelet 的默认配置模板中也始终带有 serverTLSBootstrap: true 与 featureGates.RotateKubeletServerCertificate: true,见 pkg/nodebootstrap/assets/scripts/kubelet.yaml,可见证书轮换是 eksctl 默认保证的节点安全能力,不应在自定义配置中无意丢失。
源码视角:kubeletExtraConfig 如何写入节点
理解配置如何落地到节点,有助于排查实际效果。eksctl 的节点引导(nodebootstrap)模块负责把 kubeletExtraConfig 注入 userdata,其实现路径因 AMI 家族而异(见 pkg/nodebootstrap/userdata.go 的 NewBootstrapper/NewManagedBootstrapper 分发逻辑)。
路径一:Amazon Linux 2 与 Ubuntu(cloud-init + bootstrap 脚本)
对于 AL2 和 Ubuntu,引导逻辑位于 userdata.go:linuxConfig 提取 KubeletExtraConfig 后,由 makeKubeletExtraConf 将其序列化为 JSON 并写入节点的 /etc/eksctl/kubelet-extra.json 文件:
func makeKubeletExtraConf(kubeletExtraConf *api.InlineDocument) (cloudconfig.File, error) {
...
data, err := json.Marshal(kubeletExtraConf)
...
// validate that data can be decoded as legit KubeletConfiguration
if err := json.Unmarshal(data, &kubeletapi.KubeletConfiguration{}); err != nil {
return cloudconfig.File{}, err
}
return cloudconfig.File{
Path: configDir + extraKubeConfFile,
Content: string(data),
}, nil
}
注意其中有一个隐含的校验:kubeletExtraConfig 的内容必须能被解析为合法的 KubeletConfiguration,否则引导直接失败——这从侧面说明该字段接受的正是 kubelet 配置结构。
随后,节点上的引导脚本 bootstrap.al2.sh 使用 jq 将用户配置与 eksctl 基础配置合并:
jq -s '.[0] * .[1]' "${KUBELET_CONFIG}" "${KUBELET_EXTRA_CONFIG}" > "${TMP_KUBE_CONF}"
mv "${TMP_KUBE_CONF}" "${KUBELET_CONFIG}"
这里的 jq -s '.[0] * .[1]' 是**深度合并(递归合并)**而非浅覆盖:对于 kubeReserved、featureGates 这类嵌套对象,用户配置中的键会覆盖默认值,而用户未涉及的键会保留默认值——这与前文"缺省参数自动按实例类型补默认值"的行为在机制上是一致的。
对应的单元测试验证了该写入路径,见 pkg/nodebootstrap/al2_test.go:当设置 KubeletExtraConfig: {"foo": "bar"} 时,生成的 userdata 中 /etc/eksctl/kubelet-extra.json 的内容恰为 {"foo":"bar"},权限为 0644。Ubuntu 的同一行为也有测试覆盖(ubuntu_test.go)。
路径二:Amazon Linux 2023(nodeadm + NodeConfig)
AL2023 引入了全新的节点初始化机制 nodeadm,不再使用 /etc/eks/bootstrap.sh 脚本(详见 pkg/nodebootstrap/README.md)。在 al2023.go 的 createMinimalNodeConfig 中,KubeletExtraConfig 被深度拷贝后写入 nodeadm.NodeConfig 的 spec.kubelet.config:
case *api.NodeGroup:
if nodeGroup.KubeletExtraConfig != nil {
kubeletConfig = *nodeGroup.KubeletExtraConfig.DeepCopy()
}
}
kubeletConfig["clusterDNS"] = []string{m.clusterDNS}
...
nodeKubeletConfig, err := ToKubeletConfig(kubeletConfig)
ToKubeletConfig(al2023.go)将 InlineDocument 逐键序列化为 runtime.RawExtension,最终通过 MIME 多部分 userdata 下发。测试 al2023_test.go 验证了包含 shutdownGracePeriod 与 kubeReserved(cpu: 500m、memory: 250Mi)的自定义配置能够完整出现在生成的 NodeConfig 中。
引导文件总览
无论哪种 AMI 家族,最终下发到节点的配置文件都落在 /etc/eksctl/ 目录下,核心文件包括(见 pkg/nodebootstrap/README.md 与 userdata.go):
| 文件 | 用途 |
|---|---|
/etc/eksctl/kubelet.yaml |
eksctl 基础 kubelet 配置(含 serverTLSBootstrap: true、默认 kubeReserved 等) |
/etc/eksctl/kubelet-extra.json |
用户通过 kubeletExtraConfig 注入的自定义配置 |
/etc/eksctl/kubelet.env |
kubelet 环境变量(集群名、API Server 地址、节点标签、污点等) |
AL2/Ubuntu 上 kubelet 通过 systemd drop-in 单元启动,最终以 --config=/etc/eksctl/kubelet.yaml 方式读取合并后的配置(docs/current-001-node_bootstrap.md)。
实战检查清单
将上述知识点汇总为一份可直接对照的配置清单:
- 确认 AMI 家族:
kubeletExtraConfig仅适用于 Amazon Linux 2、Amazon Linux 2023 与 Ubuntu(自管理节点组);Windows 与 Bottlerocket 不支持该字段。 - 避开保留字段:不要写入
kind、apiVersion、address、clusterDomain、authentication、authorization、serverTLSBootstrap,否则配置校验失败。 - 理解整段覆盖语义:写入
kubeletExtraConfig的字段会覆盖 eksctl 默认值;但kubeReserved缺省项会自动按实例类型补齐。 - 混合实例谨慎计算:
kubeReserved按instancesDistribution.instanceTypes中最小实例计算,尽量保持实例 CPU/内存规格一致。 - 不要遗忘证书轮换:自定义
featureGates会取消默认的RotateKubeletServerCertificate=true,务必显式写回,除非确有禁用理由。 - 验证驱逐阈值:合理设置
evictionHard(如memory.available、nodefs.available),避免资源耗尽时 kubelet 无法驱逐 Pod 导致节点NotReady。
按照上述清单操作,即可在 eksctl 创建的集群中安全地实现 kubelet 资源预留与驱逐策略的精细化控制。