kubeadm 集群配置文件详解（Ubuntu 22.04）

目标：详解 kubeadm 在 Ubuntu 22.04 上搭建 Kubernetes v1.31.14 集群涉及的各类配置文件：初始化配置（kubeadm-init.yaml）、kubelet 配置（/var/lib/kubelet/config.yaml 与 kubelet-config ConfigMap）、运行时配置（containerd config.toml）以及集群配置 ConfigMap。所有取值均来自 Ubuntu 22.04.5 实测集群。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS / x86_64
• Kubernetes：v1.31.14（kubeadm/kubelet/kubectl 1.31.14-1.1）
• 运行时：containerd 1.6.32（containerd.io 1.6.32-1）+ runc 1.1.12
• 集群：1 控制平面（kubeadm-u22-master，172.25.0.5）+ 3 worker（172.25.0.4 等）
• 示例账号：root（示例密码 q1w2e3r4）

配置文件位置总览：

二、kubeadm-init.yaml 详解

kubeadm init 推荐用配置文件指定全部参数（比命令行参数更可复现）。本集群实测使用的 /root/kubeadm-init.yaml：

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 172.25.0.5
  bindPort: 6443
nodeRegistration:
  name: kubeadm-u22-master
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
imageRepository: registry.cn-hangzhou.aliyuncs.com/google_containers
kubernetesVersion: v1.31.14
networking:
  dnsDomain: cluster.local
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
failSwapOn: false
cgroupDriver: cgroupfs
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
conntrack:
  maxPerCore: 0

2.1 InitConfiguration（init 专属）

2.2 ClusterConfiguration（集群级）

💡 默认模板（kubeadm config print init-defaults）中 imageRepository=registry.k8s.io、kubernetesVersion=1.31.0、无 podSubnet——必须按实际覆盖。

2.3 KubeletConfiguration（kubelet 组件配置）

💡 本集群 master 与 worker 统一使用 cgroupfs 驱动（containerd 对应 SystemdCgroup = false），配置一致避免了 cgroup 驱动冲突（Ubuntu 侧实测 join 全程无崩溃）。

2.4 KubeProxyConfiguration

三、kubelet 配置详解

3.1 kubelet-config ConfigMap（集群下发）

kubeadm init 时将 KubeletConfiguration 上传为 kube-system/kubelet-config ConfigMap，worker join 时自动拉取写入本机 /var/lib/kubelet/config.yaml。查看：

kubectl -n kube-system get cm kubelet-config -o yaml

💡 修改集群级 kubelet 配置的推荐方式：kubectl -n kube-system edit cm kubelet-config 修改后，重启各节点 kubelet（systemctl restart kubelet）使其重读。本集群的 ConfigMap 天然包含 cgroupDriver: cgroupfs 与 failSwapOn: false，worker 加入时自动获得一致配置。

3.2 /var/lib/kubelet/config.yaml（节点生效配置）

master 节点实际生效的关键项（实测）：

apiVersion: kubelet.config.k8s.io/v1beta1
cgroupDriver: cgroupfs
clusterDNS:
- 10.96.0.10
clusterDomain: cluster.local
failSwapOn: false
healthzBindAddress: 127.0.0.1
healthzPort: 10248
resolvConf: /etc/kubernetes/resolv.conf
rotateCertificates: true
staticPodPath: /etc/kubernetes/manifests

💡 该文件由 kubeadm 生成（join 时从 ConfigMap 下发），手工修改会被 kubeadm 下次操作覆盖；持久修改应走 ConfigMap。

3.3 kubeadm-flags.env

kubelet 启动参数文件（kubeadm 管理，勿手改）：

cat /var/lib/kubelet/kubeadm-flags.env

实测内容：

KUBELET_KUBEADM_ARGS="--container-runtime-endpoint=unix:///var/run/containerd/containerd.sock"

四、containerd config.toml 详解

containerd 1.6.32 默认配置生成：

containerd config default > /etc/containerd/config.toml

⚠️ Ubuntu 侧 apt 源默认提供 containerd.io 2.4.1，必须固定版本安装 1.6.32-1 与 master 保持一致（apt-get install -y containerd.io=1.6.32-1），否则版本不一致可能导致 CRI 行为差异。

实测生效配置的关键项（containerd config dump 验证）：

disabled_plugins = []
version = 2

[plugins."io.containerd.grpc.v1.cri"]
  sandbox_image = "registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.10"
  [plugins."io.containerd.grpc.v1.cri".containerd]
    snapshotter = "native"
    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
      SystemdCgroup = false

⚠️ 修改 config.toml 后必须重启：systemctl restart containerd。检查生效值用 containerd config dump | grep SystemdCgroup，不要只看文件（containerd 会做迁移/覆盖）。

五、镜像仓库配置（imageRepository）

控制面镜像默认从 registry.k8s.io 拉取，国内不稳定。本集群在 kubeadm-init.yaml 的 ClusterConfiguration 中全局替换为阿里云镜像仓库：

imageRepository: registry.cn-hangzhou.aliyuncs.com/google_containers

预拉取验证（实测命令）：

kubeadm config images list --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers

实测输出（v1.31.14 所需镜像清单）：

registry.k8s.io/kube-apiserver:v1.31.14
registry.k8s.io/kube-controller-manager:v1.31.14
registry.k8s.io/kube-scheduler:v1.31.14
registry.k8s.io/kube-proxy:v1.31.14
registry.k8s.io/coredns/coredns:v1.11.3
registry.k8s.io/pause:3.10
registry.k8s.io/etcd:3.5.24-0

💡 上述清单中显示 registry.k8s.io 是 --image-repository 未生效时的默认输出（v1.31 的 images list 对默认仓库直接打印）；实际 init 使用配置中的阿里云仓库拉取（kubeadm-config ConfigMap 中 imageRepository 实测为 registry.cn-hangzhou.aliyuncs.com/google_containers）。如需验证已拉取镜像：crictl images | grep google_containers。

六、kubeadm-config ConfigMap 详解

init 成功后集群内持久化 ClusterConfiguration：

kubectl -n kube-system get cm kubeadm-config -o yaml

实测关键内容：

data:
  ClusterConfiguration: |
    apiVersion: kubeadm.k8s.io/v1beta4
    certificatesDir: /etc/kubernetes/pki
    clusterName: kubernetes
    imageRepository: registry.cn-hangzhou.aliyuncs.com/google_containers
    kind: ClusterConfiguration
    kubernetesVersion: v1.31.14
    networking:
      dnsDomain: cluster.local
      podSubnet: 10.244.0.0/16
      serviceSubnet: 10.96.0.0/12

💡 kubeadm upgrade、kubeadm join（读取集群信息）都依赖该 ConfigMap；与本地 kubeadm-init.yaml 不一致时（如版本升级后），以 ConfigMap 为准。

七、kubelet resolv.conf（DNS 专项）

Ubuntu 22.04 默认 /etc/resolv.conf 由 systemd-resolved 管理（指向 127.0.0.53 stub），kubelet 使用它作为 Pod DNS 时 coredns 会检测到 loop（转发到自身）并持续 CrashLoopBackOff。本集群实测修复链：

1. 停用 systemd-resolved 并写公网 DNS：

systemctl stop systemd-resolved
systemctl disable systemd-resolved
echo -e "nameserver 223.5.5.5\nnameserver 8.8.8.8" > /etc/kubernetes/resolv.conf

2. kubelet 配置指向该文件（kubelet-config ConfigMap 或 /var/lib/kubelet/config.yaml 的 resolvConf）：

resolvConf: /etc/kubernetes/resolv.conf

3. 强制重建 coredns Pod 使新配置生效：

kubectl -n kube-system delete pod -l k8s-app=kube-dns

💡 coredns 属于 Deployment，删除后自动重建；新 Pod 以新 resolv.conf 启动，loop 告警消失。

八、常见问题（FAQ）

Q1：修改 containerd config.toml 后重启，配置不生效？ A：确认修改的是生效文件 /etc/containerd/config.toml，重启后用 containerd config dump | grep -E "SystemdCgroup|snapshotter|sandbox_image" 核对；containerd 会合并默认值，直接看文件易误判。

Q2：kubeadm config print init-defaults 输出与线上不一致？ A：print 输出默认模板（registry.k8s.io、无 podSubnet）；线上实际配置在 kubeadm-config ConfigMap。以 ConfigMap 为准。

Q3：Ubuntu 上 apt 安装 containerd.io 拿到 2.x 版本？ A：docker-ce 的 jammy 源默认最新版是 2.4.1。固定版本：apt-get install -y containerd.io=1.6.32-1，并 apt-mark hold containerd.io 防止意外升级。

Q4：改了 kubelet-config ConfigMap 但节点不生效？ A：ConfigMap 只影响后续 join 的节点；已在集群内的节点需 systemctl restart kubelet 或手工更新 /var/lib/kubelet/config.yaml 后重启。

Q5：coredns 一直 CrashLoopBackOff 且日志报 loop 检测？ A：systemd-resolved 的 stub 与 coredns 形成转发环。按第七章三步修复：停 resolved → 写 /etc/kubernetes/resolv.conf（公网 DNS）→ kubelet resolvConf 指向 → 删除 coredns Pod 重建。

参考链接

• kubeadm 配置类型说明：https://kubernetes.io/docs/reference/config-api/kubeadm-config.v1beta4/
• containerd CRI 配置：https://github.com/containerd/containerd/blob/main/docs/cri/config.md
• kubelet 配置参考：https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/
• systemd-resolved 与 kubelet 集成说明：https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/