使用 eksctl 自定义 kubelet 配置:kubeletExtraConfig 详解与节点资源预留实践

原创2026-10-13 19:36:241,630 阅读
文章标签:云原生容器编排DevOps

使用 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 自行设置,是集群正常工作的关键,不允许用户改写,包括:

  • address
  • clusterDomain
  • authentication
  • authorization
  • serverTLSBootstrap

这一限制在源码校验逻辑中有明确实现,见 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)。

实战检查清单

将上述知识点汇总为一份可直接对照的配置清单:

  1. 确认 AMI 家族:kubeletExtraConfig 仅适用于 Amazon Linux 2、Amazon Linux 2023 与 Ubuntu(自管理节点组);Windows 与 Bottlerocket 不支持该字段。
  2. 避开保留字段:不要写入 kind、apiVersion、address、clusterDomain、authentication、authorization、serverTLSBootstrap,否则配置校验失败。
  3. 理解整段覆盖语义:写入 kubeletExtraConfig 的字段会覆盖 eksctl 默认值;但 kubeReserved 缺省项会自动按实例类型补齐。
  4. 混合实例谨慎计算:kubeReserved 按 instancesDistribution.instanceTypes 中最小实例计算,尽量保持实例 CPU/内存规格一致。
  5. 不要遗忘证书轮换:自定义 featureGates 会取消默认的 RotateKubeletServerCertificate=true,务必显式写回,除非确有禁用理由。
  6. 验证驱逐阈值:合理设置 evictionHard(如 memory.available、nodefs.available),避免资源耗尽时 kubelet 无法驱逐 Pod 导致节点 NotReady。

按照上述清单操作,即可在 eksctl 创建的集群中安全地实现 kubelet 资源预留与驱逐策略的精细化控制。

登录后查看全文
eksctl