先直接说结论不管你是刚开始碰 Kubernetes还是已经被二进制方式手动部署折磨过几轮kubeadm 都是我在裸机上搭 K8s 集群的首选工具。它把证书生成、控制平面组件编排、kubeconfig 引导这些最容易出错的细节固化成一套标准流程同时也把配置暴露在你面前不会出现一键脚本跑完、出了问题完全不知道去哪看的尴尬。这篇文章以一次典型的“单控制平面 两个工作节点”部署为主线把 kubeadm 部署 K8s 全流程拆开讲透包括环境准备、containerd 配置、初始化参数、CNI 选型、节点加入和排错思路。测试环境、内部预发环境以及想要自己掌控集群的团队都可以照着这套思路落地。1. 部署前先做两个决定为什么用 kubeadm、网段怎么规划1.1 和其他部署方式相比kubeadm 到底解决什么问题Kubernetes 集群部署方式五花八门。老运维习惯直接下载二进制包把 kube-apiserver、kube-controller-manager、kube-scheduler、etcd、kubelet 一个个装好用 systemd 管起来证书全部自己签。这套流程对理论理解非常有帮助但真到要交付一个可用集群的时候效率很低而且版本越新组件之间的启动依赖越复杂。另一类是各种自动化脚本和部署平台点几个按钮集群就起来了爽是爽但一旦遇到非标准环境比如某些内网不能访问外部镜像仓库、需要自定义 SANs、指定 Node 标签和污点脚本反而成了黑盒改起来很痛苦。kubeadm 的定位刚好在两者之间。它是 Kubernetes 社区官方维护的集群引导工具思路是把控制平面的 apiserver、controller-manager、scheduler 以静态 Pod 的方式交给 kubelet 来起证书、token、kubeconfig、RBAC 规则都自动生成etcd 也因为架构的原因天然被纳管起来。你不需要手工编辑一堆 systemd unit 文件也不用担心证书签名步骤漏掉但所有关键配置仍然可以通过kubeadm init --config传入的 YAML 文件看到、改到。说白了kubeadm 把官方最佳实践固化成几个命令同时保留了可观测性这也是它在生产环境里能站住脚的原因。从维护角度看kubeadm 部署的集群还支持后面用kubeadm upgrade做版本升级证书也能用kubeadm certs renew all做续期。相比之下手工二进制部署虽然灵活但升级要手动替换二进制和证书托管集群虽然省事但控制面不在你手里很多底层的排障手段都用不上。所以我的建议是如果集群规模在几十台以内且团队需要掌握控制面细节kubeadm 是最值得投入时间的方案如果只是本地学习或临时测试可以玩更轻量的单机方案但生产交付不建议直接跳过 kubeadm 这套认知体系。1.2 节点拓扑与网段规划两个 IP 段和主机名比想象中更重要部署前先画一张拓扑图别急着敲命令。常见的入门配置是一台控制平面节点加两到三台工作节点。控制平面节点建议 4 核 8 G 起步因为 apiserver 和 etcd 都在这台机器上工作节点 2 核 4 G 在测试环境够用生产环境最好也往 4 G 以上走。主机名建议用 k8s-master、k8s-worker-01、k8s-worker-02 这种可读性强的名字并且全小写不要用下划线不要重复。后面证书里会包含节点名刚开始没规划好后续改名的成本很高。网络规划是很多人忽略的一环。集群里有三套网段节点互通的物理网段、Pod 网段、Service 网段。Pod 网段负责分配给每个 Pod 的 IPService 网段负责 ClusterIP这两段默认值分别是 10.244.0.0/16 和 10.96.0.0/12但如果你所在机房的物理机网段恰好落在这些段里必须提前改掉。最好的习惯是单独留出一段 A 类私有地址给 Pod比如 10.80.0.0/16Service 用 10.96.0.0/12并确认与所有节点、路由、防火墙规则都不冲突。否则 K8s 集群内部的转发规则可能把访问真实主机的流量劫持到 Pod 上这种问题排查起来极其费时间。这个阶段也可以顺手把 etcd 存储盘规划一下。如果条件允许etcd 的数据目录不要放在系统盘最好给一块单独的 SSD容量不用特别大但 IOPS 要够。etcd 是整套集群的“事务日志”写入性能直接影响 apiserver 的响应速度。很多集群刚搭起来没什么感觉跑几个月后频繁出现 apiserver 超时追根溯源都是这个阶段没把存储当回事。下面的实验表格可以作为规划模板角色主机名示例内网 IP建议配置磁盘控制平面k8s-master192.168.1.104C8G系统盘 50G etcd 数据盘 50G SSD工作节点k8s-worker-01192.168.1.114C8G系统盘 50G工作节点k8s-worker-02192.168.1.124C8G系统盘 50G2. 环境准备操作系统、内核参数、容器运行时2.1 基础配置swap、内核模块、时间同步少一步都不行所有节点先做同样的基础准备。Kubernetes 在 1.16 之后对 swap 的容忍度越来越低kubelet 默认不允许节点启用 swap因为 swap 会导致 Pod 的内存回收行为不可控遇到内存压力时 K8s 无法准确判断该杀哪个容器。所以在初始化之前直接把 swap 关掉并把 /etc/fstab 里对应的 swap 行注释掉不然重启之后 swap 又回来了。随后需要加载两个内核模块overlay 和 br_netfilter。overlay 是容器分层镜像的关键驱动br_netfilter 让 Linux 网桥上的数据包也能经过 iptables 规则处理这对 Pod 之间的通信和 Service 转发至关重要。可以通过一段脚本一次搞定sudo modprobe overlay sudo modprobe br_netfilter cat EOF | sudo tee /etc/sysctl.d/k8s.conf net.ipv4.ip_forward 1 net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 EOF sudo sysctl --system执行完可以用sysctl net.ipv4.ip_forward确认输出为 1。时间同步也容易被忽略但节点的时钟偏差会让证书校验和 token 校验出现“随机性”失败比如加入集群时一直报 x509 certificate cannot validate。测试环境可以用 systemd-timesyncd生产环境建议统一部署 chrony保证所有节点与同一时间源同步。这个阶段不需要在每台机器上都安装 K8s 组件但内核参数和模块必须在所有节点上执行。2.2 containerd 的配置坑SystemdCgroup 必须为 trueKubernetes 从 1.24 开始移除了对 Docker 作为容器运行时的内置支持推荐直接使用 containerd。对于大多数没有特殊诉求的集群containerd 就是最优解它同时具备 CRI 插件和原生的镜像管理能力不需要单独起守护进程。安装 containerd 的方法在 apt 系的发行版里通常是一条命令apt-get update apt-get install -y containerd.iorpm 系则对应dnf install -y containerd。装完之后不要直接拿来用先给它生成默认配置containerd config default | sudo tee /etc/containerd/config.toml然后改两个地方。第一是SystemdCgroup默认值是 false必须改成 true。原因是当前主流的 Linux 发行版都用 systemd 作为 PID 1 的 init 进程systemd 维护自己的 cgroup 树如果 containerd 和 kubelet 都使用 cgroupfs 驱动系统里会出现两套 cgroup 写入口遇到资源压力时行为会变得不可预测。改成 true 后容器的 cgroup 归属由 systemd 统一管理kubelet、containerd、runc 之间才不会打架。第二是sandbox_image也就是 pause 镜像的地址。默认的 gcr.io 地址在很多网络环境下都拉不动建议改成可以从本地镜像仓库或加速器获取的地址。修改后的配置片段大致如下[plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc] [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc.options] SystemdCgroup true [plugins.io.containerd.grpc.v1.cri] sandbox_image your-registry.example.com/pause:3.9这里有两点需要特别强调。一是改完配置必须systemctl restart containerd并且用crictl info确认 CRI 插件处于可用状态如果 crictl 不在环境里可以安装一个 cri-tools 包。二是有时候你会在网上看到把 containerd 的 CRI 插件禁用掉、再单独用 Docker 的方式这种组合在 K8s 1.24 之后完全没有必要反而引入了额外的脆弱链路。直接让 containerd 承担 CRI 职责部署路径最干净。2.3 安装 kubeadm、kubelet、kubectl 并锁版本三个组件必须一起装版本不一致会在初始化时给出莫名其妙的报错。先配置好 Kubernetes 官方软件源然后用包管理器安装最后锁定版本。锁定这一步很重要否则哪天执行apt upgrade顺手把 kubelet 升到了小版本控制面还是旧版本整个集群可能只能从集群外部的备份里恢复。锁定命令在 apt 系里是apt-mark hold kubelet kubeadm kubectlrpm 系使用yum versionlock kubelet kubeadm kubectl。安装完成后用kubeadm version和kubelet --version各查一遍确认输出的一致。这里我用 Kubernetes 1.28.2 作为示例版本实际选型时申请接近当前稳定版、又小幅滞后的版本会比较稳妥因为生态里的插件和 Operator 对新版本的支持往往有延迟太新的版本容易踩到兼容性边界。apt-get update apt-get install -y kubelet1.28.2-1.1 kubeadm1.28.2-1.1 kubectl1.28.2-1.1 apt-mark hold kubelet kubeadm kubectl如果内部环境无法直接访问外部软件源需要在搭建前把对应版本的安装包同步到本地镜像仓库并把 apt/dnf 源切换为内部地址。kubelet 这个服务装好后可以先systemctl enable kubelet但先不要 start因为现在还没有/etc/kubernetes下的配置文件强行启动只会反复报错。等 kubeadm init 生成配置后kubelet 会在正确的文件出现后自己起来。3. 核心环节用 kubeadm init 初始化控制平面3.1 把参数写进 YAML别在命令行里堆很多新手喜欢把参数直接拼在kubeadm init --apiserver-advertise-address 192.168.1.10 --pod-network-cidr ...后面。这当然能跑通但几个关键参数堆在一条命令里可读性差也不方便保留记录。我这里更推荐写一个配置文件比如kubeadm-config.yaml把初始化意图固定下来下次重置后重放也方便。一个可用的配置示例apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: 192.168.1.10 bindPort: 6443 nodeRegistration: name: k8s-master criSocket: /run/containerd/containerd.sock --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: 1.28.2 controlPlaneEndpoint: 192.168.1.10:6443 networking: serviceSubnet: 10.96.0.0/12 podSubnet: 10.244.0.0/16第一个InitConfiguration里的localAPIEndpoint表示 apiserver 监听在本机的哪个地址和端口。如果机器有多个网卡必须显式指定内网网卡 IP否则 kubeadm 可能选一个容器网卡或管理网卡地址导致后续节点怎么都连不上。controlPlaneEndpoint在单机场景可以跟 advertiseAddress 一样但在高可用场景会指向一个 VIP 或负载均衡器地址所有工作节点都通过这个地址访问 apiserver。nodeRegistration.name提前指定好节点名避免从默认主机名生成criSocket指向 containerd 的 socket一般不需要改。ClusterConfiguration里的podSubnet和serviceSubnet要和前面规划一致这两个值必须集群全局统一初始化之后基本无法修改。imageRepository这一项默认会指向官方镜像仓库如果环境拉镜像有困难可以替换成内网镜像仓库地址。但要注意除 pause 等少量镜像外K8s 组件镜像的完整路径是由 kubeadm 拼接的替换仓库时只需要保证目录结构和 tag 一致不要动根路径规则。3.2 执行 init 后输出里藏着最重要的 join 信息配置就绪后执行sudo kubeadm init --config kubeadm-config.yaml --v5--v5是为了把执行细节打出来万一失败日志会比默认输出丰富得多。init 过程会先做一轮 preflight 检查任何不满足的条件都会在这里报出来比如 swap 没关、内核参数不对、容器运行时没就绪。这时候停止命令按照提示修改不需要反复尝试--ignore-preflight-errors那等于让有问题的节点带着隐患进入集群。init 做完之后会输出一大段内容其中最关键的是两行kubeadm join命令和对应的--discovery-token-ca-cert-hash参数。这段 join 指令只在 token 有效期内可用默认 24 小时所以要么立刻保存要么后面用kubeadm token create --print-join-command重新生成。不要关闭终端窗口后才发现没复制这种情况我碰到过好几次。控制面组件这时以静态 Pod 形式出现在/etc/kubernetes/manifests目录下kubelet 会自动探测并启动它们。用kubectl get pods -n kube-system可以看到 apiserver、etcd、controller-manager、scheduler 都在 Running 状态但 CoreDNS 大概率还在 Pending。这是正常现象因为网络插件还没装Pod 之间无法通信CoreDNS 的 Pod 调度起来也拿不到可用 IP。初始化完成后需要把 kubectl 的配置文件放到当前用户目录mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config之后用kubectl get nodes能看到控制平面节点处于 NotReady同样不要慌这是 CNI 缺失的表现。下一步就是装网络插件。3.3 高可用场景预留controlPlaneEndpoint 和证书 SANs如果你不是只玩单控制面而是在筹备生产集群channels 上要注意controlPlaneEndpoint不要写死成某一台机器的 IP而应该写一个负载均衡器或 VIP 地址。比如三个控制面节点前挂着一个内网 VIP那controlPlaneEndpoint写成192.168.100.10:6443工作节点全部连这个地址。这样即使某个控制面节点宕机其他节点可以通过负载均衡器继续提供 apiserver 能力。证书 SANs 同样要提前规划。apiserver 的证书里会记录允许访问的主机名和 IP如果后期要用 VIP、域名、负载均衡器地址访问集群初始化时就要把 SANs 加进去。最佳实践是在ClusterConfiguration里追加apiServer: certSANs: - 192.168.100.10 - k8s-api.example.com如果第一次初始化时漏了后面再想把 SANs 加进去就得重新签证书并重启 apiserver虽然不算特别难但生产集群里做这种操作需要申请变更窗口麻烦得很。宁可现在多写几个地址也不要等到集群运行后再折腾。4. 网络插件装好后集群才真正“活”过来4.1 CNI 选型Flannel、Calico、Cilium 怎么选没有 CNI 插件Pod 之间无法跨节点通信Service 的 ClusterIP 也不过是一堆 iptables 规则的空壳。社区里最常见的三个选择是 Flannel、Calico、Cilium它们的思路差异很大直接影响后续运维。项目数据面NetworkPolicy性能特点运维复杂度FlannelVXLAN/Host-GW不支持原生策略简单轻量适合小规模/测试低CalicoBGP/VXLAN支持丰富路由直连生产常用中CiliumeBPF支持且精细性能强适合大规模/云原生网络较高如果你纯粹想把集群搭起来跑一个 DemoFlannel 最省心如果集群要跑真实业务并且有严格的网络策略要求Calico 是比较稳妥的中庸选择如果你已经有一些 eBPF 相关基础设施对可观测性要求极高那 Cilium 可以优先考虑。结合大多数场景我会建议直接上 Calico原因有二一是它有成熟的 BGP 模式可以把 Pod 路由直接广播到三层网络性能比 VXLAN 封装好很多二是 NetworkPolicy 是 K8s 安全模型的重要组成Flannel 不支持后续补起来要换 CNI代价很大。4.2 安装 Calico 并校准 IP 池最容易忽略的配置Calico 一般用清单文件部署。先下载calico.yaml打开后找到环境变量CALICO_IPV4POOL_CIDR这决定了 Calico 管理的 IP 池。一个最常见的错误是这里保持默认的192.168.0.0/16而 kubeadm init 配的podSubnet是10.244.0.0/16两个网段对不上Calico 虽然可以启动但给 Pod 分配的 IP 和集群期望的网络不在一个平面节点永远没办法 Ready。所以安装前先强制改成和 podSubnet 一致的值比如- name: CALICO_IPV4POOL_CIDR value: 10.244.0.0/16然后执行kubectl apply -f calico.yaml推荐在初始化控制面之后、工作节点加入之前先装好 Calico。原因很简单工作节点加入后kubelet 会尝试通过 CNI 获取 Pod IP 并设置网络如果此时 CNI 还没准备好虽然节点最终也能恢复但会多出一些无谓的报错和短暂的不健康状态。装好之后观察kubectl get pods -n kube-system -o widecalico-node 以 DaemonSet 方式在每个节点上运行等它们都 Runningkubectl get nodes里的控制面节点就会变成 Ready。4.3 安装完成后的第一次网络验证不要只看节点状态实际跑一个测试 Pod 更可靠。创建一个简单的命名空间和两个副本或者用kubectl run快速拉起一个 Podkubectl create deployment net-test --imagebusybox --replicas2 -- sleep 3600 kubectl get pods -o wide等两个 Pod 都在 Running 后进入其中一个ping 另一个 Pod 的 IP。如果通了说明跨节点 Pod 通信链路是 OK 的同时用kubectl exec去解析kubernetes.default.svc.cluster.localConfirm Service 的 DNS 和 ClusterIP 也能连通。这时集群才算基本可用CoreDNS 也自然会从 Pending 变为 Running。5. 工作节点加入与集群验证5.1 重新生成 join 命令token 管理和必要参数工作节点不需要安装控制面组件但需要 containerd、kubelet、kubeadm基础环境也要跟前面一样准备好。然后只需要在控制平面节点上执行kubeadm token create --print-join-command它会把带 token 和 ca cert hash 的完整 join 命令打印出来。token 默认 24 小时有效如果你复制的命令过期了重新生成即可。输出类似kubeadm join 192.168.1.10:6443 --token a1b2c3... --discovery-token-ca-cert-hash sha256:...在工作节点上用 root 执行这条命令前确认两件事一是节点的时间同步正常时间偏差会让证书校验失败二是节点的主机名不要和控制面节点重复否则 apiserver 的证书和 NodeName 校验会出问题。执行 join 后kubelet 会立刻连接到 apiserver并通过证书请求流程拿到自己的身份凭证。整个 join 过程不需要手动创建任何证书这也是 kubeadm 简化部署的典型体现。如果工作节点之前用kubeadm init误操作过或者已经加入过其他集群必须先kubeadm reset清理否则 preflight 检查会被 /etc/kubernetes 下的旧配置干扰。join 成功后在控制面节点上运行kubectl get nodes新节点应该从 NotReady 在几十秒内变为 Ready。5.2 加入后的验证清单从节点状态到业务流量节点加入后不能只盯着Ready还要把集群的关键链路完整验证一遍。我的常规顺序是kubectl get nodes -o wide确认所有节点状态、IP、Kubernetes 版本一致。kubectl get pods -n kube-system -o wide确认每个节点上的 calico-node、kube-proxy 都在 Running。创建一个 Deployment增加副本数让 Pod 调度到不同节点上观察跨节点调度是否正常。创建一个 NodePort Service访问 http://任意节点IP:NodePort确认流量能转发到后端 Pod。第 4 步非常有用它同时验证了 kube-proxy 的 iptables 转发规则、CNI 的跨节点封装、Service 的负载均衡语义。很多集群看起来是 Ready 的但 NodePort 端口不通一查才发现 kube-proxy 的 mode 和内核模块有问题。默认 kubeadm 生成的 kube-proxy 配置使用 iptables 模式对大多数场景足够了如果网络规模很大建议后续再调研 ipvs 模式对应的内核模块是ip_vs系列需要在节点上提前加载。6. 常见问题与排查技巧实录6.1 kubelet 一直 CrashLoop日志和镜像仓库是突破口kubelet 是离操作系统最近的一个组件它的日志基本覆盖了初始化阶段所有问题。遇到 kubelet 启动失败第一件事就是看journalctl -u kubelet --no-pager -n 100常见错误有三种。第一种是failed to run Kubelet: misconfigured... cgroup driver这说明 kubelet 的 cgroup driver 和 containerd 不一致回到 2.2 节确认 containerd 的SystemdCgroup是否为 true。第二种是failed to get sandbox image ... connection refused说明 containerd 的 CRI 插件没有正常监听或者 sandbox_image 配置被改坏。第三种是node xxx already exists说明之前在该节点上部署过集群需要先kubeadm reset清理旧状态然后清掉/etc/kubernetes目录或者至少备份后删掉再重新初始化或 join。镜像拉取慢是另一个隐性问题。如果控制平面的 Pod 一直处于ContainerCreating执行crictl ps -a看状态再用crictl inspect查看镜像是否已经存在到本地。本地没有镜像时应该先确认 containerd 的 registry mirror 配置是否生效而不是反复重启 kubelet。大量镜像拉取重试可能把仓库限流造成集群内所有节点都排队这个坑我踩过不止一次。6.2 Node 一直 NotReady八成是网络插件在闹脾气如果节点的 Conditions 里Ready是 False但 kubelet 进程又是活的先看kubectl describe node nodeName输出的 KubeletNotReady 原因再用kubectl get pods -n kube-system -o wide检查 calico-node 或 flannel pod 是不是还在 CrashLoop。网络插件 DaemonSet 的日志基本都指向同一个点Pod 网段和 CNI 配置的 IP 池不一致导致节点在建立网络时反复报calico/node failed: error。遇到这种情况最快的结局不是硬改 CNI 环境变量而是先执行kubeadm reset把节点清理干净然后修改kubeadm-config.yaml里的podSubnet重新 init/join再重新 apply 一份与它完全匹配的 CNI 清单。虽然重置听起来粗暴但相比在一堆不一致的状态里打补丁效率要高得多。另一个常见原因是节点防火墙把 VXLAN/BGP 需要用的端口挡掉了比如 4789/UDP、179/TCP这种问题从 pod 日志里反而不太好识别需要结合节点网络策略一起排查。6.3 证书有效期与升级提醒别等到期才动手kubeadm 生成的集群证书默认有效期只有一年这对集群是悬在头上的一根刺。要定期执行kubeadm certs check-expiration查看所有证书的到期时间并接入监控告警。续期的命令是kubeadm certs renew all续完之后不用重新初始化集群但需要重启和证书相关的静态 Pod可以直接删除/etc/kubernetes/manifests下的对应清单文件让 kubelet 重建也可以粗暴地重启 kubelet 把所有控制面组件重拉一遍。升级路径同样依赖kubeadm upgrade plan和kubeadm upgrade apply 版本。这里要特别提醒升级前一定要备份/etc/kubernetes和 etcd 数据目录尤其是 etcd一旦升级过程中出现版本不兼容你最终能依赖的只有备份。我在某次模拟项目 X 的升级演练中因为没有备份 etcd升级到一半发现 apiserver 起不来最后只能回滚到老版本重新恢复白白折腾了一个晚上。生产集群的升级节奏一定是“先低风险环境验证再控制面最后工作节点”不要反过来。6.4 零零散散的坑快速查错表最后把一些琐碎但高频的问题整理成速查表适合贴在笔记本上现象常见原因快速处理kubelet 无法启动报 swap 相关swap 未关闭swapoff -a并注释 /etc/fstabNode Ready 很久又掉线节点时间漂移检查 chrony/systemd-timesyncd同步时间Pod 一直 Pending缺少 nodeSelector 或资源不足kubectl describe pod查看调度事件容器反复重启镜像拉取失败或探针失败crictl ps -a和kubectl logsjoin 时提示 token 过期token 默认 24h 有效期kubeadm token create --print-join-command重新生成API Server 证书校验失败certSANs 缺了访问地址初始化前加全或重新签证书从长期运维角度讲我会建议把初始化配置、CNI 配置、节点初始化脚本都放到版本管理里而不是靠人肉记忆。kubeadm 固然能让部署过程标准起来但真正让集群稳定运行的是你对待这些配置的态度——每一条记录都有出处每一次变更都有回滚方案遇到问题先看日志再动手。这样部署一套 K8s才是真正把控制能力握在了自己手里。最后再说一个我自己的习惯每次装完一个节点我都会先执行journalctl -u kubelet --no-pager | tail -50看到日志里没有 fatal 错误再继续下一步。这套流程跑顺之后kubeadm 部署 K8s 其实就是复制粘贴但排错能力是复制不来的坑踩过一次记录一次下次就能少走很多弯路。
