说实话第一次自己动手搭 Kubernetes 1.31 集群的时候我还在老老实实一条条敲命令。一个 Master 加两个 Worker敲完内核参数、换源、装容器运行时、再初始化、配置网络插件一整套下来小半天就没了。更烦的是换一台机器、重装一次环境同样的命令又得从头来过错一个字符到后面排查起来就特别崩溃。后来我把这套流程沉淀成了两个脚本——一个初始化 Master一个初始化 Worker从此以后部署集群基本就是执行脚本 喝杯水的事。如果你也准备上手 Kubernetes 1.31或者不想把时间耗在重复的初始化命令上这篇文章就是给你准备的。我会把双脚本的拆分逻辑、每一步命令背后的原因、踩过的坑以及整个集群从执行到验证通过的过程全部拆开来讲。内容不追求高深但求每一步都清楚让你不仅能跑通还能知道为什么这样写。1. 为什么是双脚本Master与Worker的初始化差异决定了拆分边界先聊一个核心问题既然是快速部署为什么不直接写一个大脚本在每台机器上跑一遍很多人一开始都是这么想的但实际跑过就会发现Master 和 Worker 在集群里的职责完全不同初始化的动作差异非常大强行合并成一个脚本只会让逻辑越来越绕。Master 节点要做的事是生——生成集群。它需要承载控制面组件也就是 API Server、Controller Manager、Scheduler 和 etcd这些组件通过kubeadm init一次性拉起。Master 脚本里必须包含集群初始化动作执行完会生成证书、admin.conf 配置文件以及给 Worker 用的 join 令牌。而 Worker 节点的核心动作是入——加入集群也就是执行kubeadm join把当前节点注册进已有的控制面里。同一个脚本如果既包含 init 又包含 join脚本就必须去判断当前机器到底扮演什么角色判断条件越多出错的面就越大。再往细了看Master 初始化完成后还有一些收尾动作只有 Master 能做配置kubectl的访问凭证、安装 CNI 网络插件、生成 Worker 节点的 join 命令并保存到文件。这些动作放到 Worker 脚本里没有任何意义。反过来Worker 脚本需要做的事情则简单很多内核参数、容器运行时的部分可以复用同一段逻辑但集群初始化相关的代码完全不需要。双脚本方案的第二个好处是可控性。初始化集群是有顺序的必须先 Master 后 Worker而且所有节点在加入前Master 必须已处于 Ready 状态。脚本拆开之后执行顺序天然清晰先跑 Master 脚本跑完之后把生成的 join 指令带到 Worker 上跑 Worker 脚本就行。如果过程中某一步失败了你也能精准定位是哪台机器、哪个阶段的问题而不是在一个巨型脚本里从头到尾摸黑排查。还有一个容易被忽略的理由可维护性。Kubernetes 版本升级时Master 和 Worker 端的变更节奏往往不同步。版本升级时控制面的kubeadm init参数、CNI 版本、镜像地址可能需要单独调整而 Worker 侧通常只需要更新 kubelet、kubeadm 的版本。如果只有一个脚本每次升级都要在一个文件里反复腾挪很容易动一处伤另一处。拆开之后各自独立维护升级一个版本就是改两个文件里各自对应的那几行清晰得多。2. 动手写脚本前必须先敲定的四个关键决策脚本不是凭空写的。在我把命令落盘之前先花了半小时确定了几件非常重要的事这些决策直接影响脚本的稳定性和后续扩展性。2.1 版本锁定kubeadm、kubelet、kubectl 必须同一版本线Kubernetes 社区的版本策略是kubelet 版本必须小于等于 kubeadm 版本实操中为了省心最佳实践是让所有组件保持完全同版本。我这次部署用的是 1.31 版本线所以脚本里 kubeadm、kubelet、kubectl 安装时都要指定版本号而不是直接装 latest。如果装了不同版本的组合kubeadm init的阶段大概率会因为 API 版本不匹配而中断。这里我用的安装方式是 apt 源锁定版本。具体来说在/etc/apt/sources.list.d/kubernetes.list里配置好官方源之后用apt-cache madison kubeadm可以列出所有可用版本然后在安装命令里直接指定版本号外加hold操作防止意外升级apt-get install -y kubelet1.31.0-* kubeadm1.31.0-* kubectl1.31.0-* apt-mark hold kubelet kubeadm kubectl容器运行时我选择 containerd版本 1.7.x。这里有个关键配套动作containerd 和 Kubernetes 是通过 CRI 接口通信的版本上只要保证 containerd 官方支持 Kubernetes 1.31 即可不需要和 kubeadm 保持同一个版本号。我在生产实践中更推荐 containerd 而非 docker 作为运行时因为 containerd 更轻、CRI 兼容更直接不需要额外装 docker-shim。2.2 cgroup 驱动一律使用 systemd这是初始化容器运行时阶段最容易踩的坑。Kubernetes 从 1.21 开始建议 kubelet 与容器运行时使用 systemd cgroup 驱动而 containerd 2.x 的某些发行版默认配置仍然是 cgroupfs。如果两边驱动不一致kubelet 启动后大概率会报failed to run Kubelet: misconfiguration: kubelet cgroup driver: systemd is different from docker cgroup driver: cgroupfs。我的处理方式是在 Master 和 Worker 脚本里都加了一段 containerd 配置修正逻辑强制把/etc/containerd/config.toml里的SystemdCgroup设为truemkdir -p /etc/containerd containerd config default | sed s/SystemdCgroup false/SystemdCgroup true/ /etc/containerd/config.toml systemctl enable --now containerd这段命令的逻辑是先用containerd config default生成一份完整的默认配置再用 sed 替换关键行。注意不要自己在配置文件里手写有限几行配置containerd 的默认配置包含了很多重要的参数项直接覆盖会导致运行时行为异常。2.3 网络插件与 Pod CIDR我选了 Flannel 配 10.244.0.0/16Kubernetes 本身不提供 Pod 间网络初始化之后必须手动安装一个 CNI 插件否则节点状态永远是 NotReadyPod 永远调度不上去。主流的 CNI 有 Calico、Flannel、Cilium 等我这次选的是 Flannel理由很实际它是一个纯 overlay 网络方案部署最轻量配置文件直接 apply 就能用不依赖额外的数据面组件而且对实验环境、中小规模集群来说性能足够。代价是功能上比 Calico 少一些比如 NetworkPolicy 默认不支持。选择了 Flannel 也就确定了 Pod CIDR 必须使用10.244.0.0/16因为 Flannel 的默认配置文件里预设了这个网段。如果在kubeadm init时指定了别的 Pod 网段应用 Flannel 配置文件后会网段冲突点位之间完全不通。所以脚本里要写死kubeadm init \ --apiserver-advertise-address${MASTER_IP} \ --pod-network-cidr10.244.0.0/16 \ --kubernetes-version1.31.02.4 主机规划与前置检查时间同步、合理主机名、swap 关闭很多新手初始化失败的反而不是 kubeadm 本身而是基础环境不达标。kubeadm 的 preflight 检查非常严格任何一个条件不满足都会中断。我在脚本里内置了以下三项处理第一swap 必须关闭。Kubernetes 1.31 的 kubelet 默认还不支持启用 swap 的节点所以脚本里执行swapoff -a只是临时关闭还需要在 fstab 里注释掉 swap 条目保证重启后依然生效。第二时间同步必须做好证书校验强依赖时钟一致性我会在初始化之前确保 chrony 服务正常运行。第三主机名不能重复也不能包含下划线等特殊字符。两个 Worker 如果重名注册时节点会互相覆盖表现非常诡异。最好在跑脚本前手动设置好有区分度的 hostname。3. Master初始化脚本逐段拆解从内核调优到CNI安装一气呵成现在进入正式内容。我会把 Master 脚本的设计思路按执行顺序拆开每一段函数解决什么、为什么要这样写都会说清楚。这段脚本在初始化一个干净机器时可以直接复制使用但更建议你理解了之后再根据实际环境微调。3.1 预检与公共依赖安装脚本第一段是预检逻辑。因为是快速部署我不想让脚本跑到一半因为权限、缺依赖之类的问题失败所以预检写得很凶#!/usr/bin/env bash set -euo pipefail MASTER_IP${1:?Usage: $0 master_ip} POD_CIDR${POD_CIDR:-10.244.0.0/16} if [[ $EUID -ne 0 ]]; then echo 必须使用 root 账号执行本脚本 exit 1 fi # 关闭 swap 并注释掉 fstab 中的条目 swapoff -a sed -ri s/.*swap.*/#/ /etc/fstab # 加载内核模块 modprobe overlay modprobe br_netfilter cat /etc/modules-load.d/k8s.conf EOF overlay br_netfilter EOFoverlay模块是 containerd 的 overlayfs 存储驱动要用的br_netfilter则是让 iptables 能处理 bridge 流量Kubernetes 的 Service 转发依赖这个能力。只执行modprobe还不够万一重启后会丢失所以我在/etc/modules-load.d/k8s.conf里固化了下来。3.2 sysctl 参数设置让内核允许流量转发接着写 sysctl 配置。Kubernetes 节点需要开启 IP 转发并且要让 iptables 能看见 bridge 上的流量cat /etc/sysctl.d/k8s.conf EOF net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 EOF sysctl --system很多人会漏掉第一行。如果net.bridge.bridge-nf-call-iptables不设为 1从 Pod 发往 Service 的流量可能会在 bridge 层被绕过 iptables 规则导致 Service 负载均衡失效。这个参数在旧内核上是默认关闭的所以必须显式打开。不用纠结这些参数为什么这么难记这是 Kubernetes 官方文档 preflight 检查中的标准配置项照做就行。3.3 容器运行时与 kubeadm 工具链安装安装 containerd 和 kubeadm 工具链的代码占了脚本近一半的篇幅。这里我不推荐用发行版自带的 containerd版本更新滞后且配置路径不一致。我的做法是直接配置 docker apt 源来装 containerd然后通过 kubernetes apt 源装 kubeadm 全家桶apt-get update apt-get install -y containerd.io kubelet_install() { curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg echo deb [signed-by/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ / /etc/apt/sources.list.d/kubernetes.list apt-get update apt-get install -y kubelet1.31.* kubeadm1.31.* kubectl1.31.* apt-mark hold kubelet kubeadm kubectl }这里有个版本细节值得留意官方源目录结构里带了v1.31这个路径层级不同大版本对应不同的源目录。如果你的环境是 1.30 或 1.32源地址里的版本号也要跟着变否则 apt 会告诉你找不到安装包。3.4 集群初始化与kubectl配置工具链装好、containerd 配置完SystemdCgroup true之后就可以正式初始化集群了。我的脚本在 init 前加了一个状态判断避免重复执行时二次 initif [[ ! -f /etc/kubernetes/admin.conf ]]; then kubeadm init \ --apiserver-advertise-address${MASTER_IP} \ --pod-network-cidr${POD_CIDR} \ --kubernetes-version1.31.0 fi--apiserver-advertise-address必须指定为 Master 的局域网 IP也就是说脚本需要你传入一个参数不能写成0.0.0.0或 default。这决定了其他节点通过哪个地址访问 API Server写错了 Worker 将永远无法加入集群。初始化完成后/etc/kubernetes/admin.conf会生成管理员证书和访问配置。脚本接下来自动配置当前用户的 kubectlmkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config注意cp -i如果目标已存在会交互式询问是否覆盖。脚本模式里如果担心卡住建议改成cp -f。我自己实际用的时候改成了强制覆盖因为重复执行脚本本来就是为了最后一次配置生效。3.5 CNI安装与join命令落盘集群拉起后核心组件都处于 Running 状态但节点还是 NotReady因为没有任何一个 CNI 插件承担 Pod 网络。我直接用 kubectl 应用官方 Flannel 配置文件kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml关键一步来了。Worker 脚本需要执行的kubeadm join命令并不是凭空生成的它包含一个一次性令牌和 CA 证书的哈希指纹而这两样只有在 Master 初始化完成之后才会产生。所以 Master 脚本跑完之后我让它自动把 join 命令落盘保存存到一个固定路径kubeadm token create --print-join-command /root/k8s_join_cmd.sh chmod x /root/k8s_join_cmd.sh--print-join-command会直接输出一条完整的kubeadm join命令包括 token 和 CA hash。把这个内容重定向到文件后Worker 脚本可以从这个文件里读取并执行整个过程不需要手工复制任何信息。这个设计的细节我会在下一节里展开。4. Worker加入脚本逐段拆解Join凭证的获取与落地实现Worker 脚本的骨架和 Master 有约 60% 是重合的——预检、swap 关闭、内核模块、sysctl、containerd 安装、kubeadm 工具链安装这些都完全一致。这也是为什么我建议你把公共初始化逻辑抽出来或者在两个脚本之间复制保持一致。我在实际项目中其实是把公共部分直接复制到两个脚本里的因为它们会分别在各自节点上跑互相调用的依赖关系越少越好。4.1 Join命令的三种获取方式与最终选择Worker 脚本真正和 Master 不同的部分只在最后一段怎么拿到 join 命令并执行。这里我对比过三种方式第一种在 Master 上把/root/k8s_join_cmd.sh的内容通过 SSH 分发到 Worker。这种方式自动化程度最高但要求所有节点之间配置了免密登录对一台全新机器来说多了一层前置配置负担不够快速。第二种用配置管理工具如 Ansible 做统一分发、统一执行。这当然是最工程化的方案但会让双脚本变成双脚本配置管理工具三件套增加学习成本。对于个人实验或小规模集群有点重。第三种也是我最终采用的Worker 脚本接收 Join 命令文件路径作为参数或者更简单一点脚本里写死从同一个文件读取。实际部署时通过 USB、scp、文件共享或者任何顺手的工具把/root/k8s_join_cmd.sh传到 Worker 的对应路径即可。等 Worker 完成基础环境初始化后直接执行这个脚本文本。实际使用中我用了一个更省事的小技巧Master 脚本跑完后在最后几行把生成的 join 命令内容也一并输出到终端。这时候我只需要复制这行输出作为参数传给 Worker 的 join 脚本就行连文件传输都省了。所以 Worker 脚本里有一小段逻辑允许你把 join 命令作为字符串参数传进来JOIN_CMD${1:-$(cat /root/k8s_join_cmd.sh 2/dev/null)} if [[ -z $JOIN_CMD ]]; then echo 找不到 join 命令请从 Master 拷贝 /root/k8s_join_cmd.sh 的内容 exit 1 fi4.2 Worker脚本执行与状态确认当所有前置准备就绪Worker 脚本最终执行的就是这段eval $JOIN_CMD为什么用eval而不是bash $JOIN_CMD因为当 JOIN_CMD 是直接传进来的字符串参数时用bash执行需要先写入文件而eval直接在当前 shell 上下文执行适合这种场景。如果 JOIN_CMD 是从文件读的那两种写法等价。执行完 join 之后脚本还会做一次状态确认询问用户是否要在 Master 上检查节点状态echo Worker 已成功加入集群。可在 Master 节点执行: kubectl get nodes我用了一段简单的循环等待让脚本在 join 后持续检查 kubelet 是否存活直到输出active (running)或超时退出。这比直接打完命令就结束要可靠得多能第一时间发现因为版本不匹配、证书问题导致的 kubelet 启动失败。Worker 脚本的核心就这么简单。相比 Master 脚本的重Worker 脚本真正独有部分只有 join 凭证的获取和最终执行其余的都是在为这段服务。这也是为什么你会看到 Worker 脚本里同样完整地写了 sysctl 和 containerd 配置——缺少任何一部分kubelet 都无法在这个节点上正常拉起 Pod。5. 双节点实测从脚本执行到Pod跨节点通信的完整验证纸上谈兵到此结束。我拿一台临时环境做了完整实测两台虚机一台扮演 Master一台扮演 Worker。配置是 4C8G操作系统 Ubuntu 22.04 LTS内核版本 5.15。这个配置足够跑 Flannel 加几个测试 Pod。5.1 执行顺序与耗时的真实记录首先是 Master 节点。上传脚本后执行chmod x master_init.sh ./master_init.sh 192.168.31.10脚本执行耗时大约在 5-7 分钟时间大头全部花在 apt 安装和拉取镜像上。第一次看到 kubeadm init 输出的那一大串内容不要慌只需要关注最后几行。我实测中最后的输出里有这么一段关键信息Your Kubernetes control-plane has been initialized successfully!接着脚本自动执行完了 kubectl 配置和 Flannel 安装。我在 Master 上执行kubectl get nodes输出如下NAME STATUS ROLES AGE VERSION master-1 Ready control-plane 3m10s v1.31.0注意 STATUS 要在Ready状态。这中间有个时间差Flannel 的 Pod 要先拉镜像、启动然后节点才会从 NotReady 变 Ready。期间如果看到NotReady别急着排查等一两分钟再kubectl get nodes大概率已经恢复正常。接下来是 Worker 节点。我把 Master 上生成好的/root/k8s_join_cmd.sh拷贝到 Worker然后执行chmod x worker_init.sh ./worker_init.shWorker 脚本执行时间更短大概 3-4 分钟因为不需要拉控制面镜像。执行完后回到 Master再次查看节点状态kubectl get nodes NAME STATUS ROLES AGE VERSION master-1 Ready control-plane 15m v1.31.0 worker-1 Ready none 2m20s v1.31.0如果 Worker 一直处于 NotReady最常见的两个原因我留在下面的踩坑清单里说。5.2 部署测试Pod验证跨节点通信节点 Ready 不代表网络没问题。我用最简单的 Nginx Deployment 做了连通性测试副本数设置为 2这样两个副本大概率会被调度到不同节点上kubectl create deployment nginx --imagenginx --replicas2 kubectl rollout status deployment/nginx kubectl get pods -o wide看到两个 Pod 分别运行在 master-1 和 worker-1 上之后再验证跨节点访问。进入其中一个 Pod去 curl 另一个 Pod 的 IPkubectl exec -it pod-a -- curl pod-b-ip能返回 Nginx 页面说明两个节点上的 Pod 网络已经通了VXLAN 隧道正常Flannel 配置无误。这一步是整条链路最后的承重墙。如果这里不通问题会集中在 Flannel 的网段配置或者交换机对 VXLAN 流量的限制上排查思路和 Service 调不通完全不同。5.3 我踩过的几个常见坑与此解决方案部署过程中我特意复现了几个高频故障看看脚本是否能承受顺便记录下处理方式。第一token 过期。kubeadm 默认创建的 bootstrap token 有效期是 24 小时。如果生成的 join 命令放了超过一天没用Worker 执行 join 就会报 token 过期。解决方式是回到 Master 重新执行一次kubeadm token create --print-join-command把新命令传给 Worker。我的脚本里已经把这一步独立封装了所以临时加节点时不用重新初始化集群。第二主机名冲突。我有一次因为忘记设置主机名两台机器都叫 ubuntu结果 Worker 注册后Master 上的节点列表里只显示一个节点而且两个节点的名字互相覆盖。解决方法是分别在两台机器上执行hostnamectl set-hostname master-1和hostnamectl set-hostname worker-1然后重新 reset 并加入。第三版本不匹配。Worker 脚本里如果 apt 装到的是 1.31.1而 Master 初始化时用的是 1.31.0kubelet 和 kubeadm 的版本一般不会造成致命问题但 kubelet 与 API Server 的次版本差距超过一个版本时连接就会失败。这也是脚本里显式 lock 版本的原因。遇到这种情况时kubeadm reset后重新执行 Worker 脚本即可。6. 脚本沉淀后的扩展加节点、重跑与集群重置双脚本方案一旦跑通你接下来一定会遇到这几个场景集群扩容加 Worker、脚本因为故障需要重跑、整个环境推倒重建。这些场景不写进脚本里的话每次都会手忙脚乱。我把扩展思路一并写在最后。6.1 加新Workertoken过期后的快速处理新加一台 Worker 时Master 上原来生成的/root/k8s_join_cmd.sh大概率已经过期。不用重新跑 Master 脚本只要在 Master 上执行kubeadm token create --print-join-command拿到新命令后在 Worker 上直接执行即可。前提是 Worker 已经装好了 kubeadm、kubelet 这些组件。如果你复用了我上面的 worker_init.sh就会看到它已经支持把 join 命令字符串直接作为参数传入./worker_init.sh kubeadm join 192.168.31.10:6443 --token xxxxx --discovery-token-ca-cert-hash sha256:xxxxx这比重新拷贝文件再执行要顺滑得多。6.2 重跑脚本是否安全我的 Master 脚本本身是幂等的——只要admin.conf存在就跳过 init 直接走后续 kubectl 配置和 CNI 安装。但如果你真的想完全重来不能只靠重跑脚本要先销毁已有集群kubeadm reset -f rm -rf /etc/cni/net.d $HOME/.kube然后重新执行 Master 脚本。Worker 同理执行kubeadm reset -f后重新跑 worker_init.sh。如果你遇到节点状态异常想剔除旧节点在 Master 上用kubectl drain加kubectl delete node的标准流程也可以这个问题和脚本关系不大不展开讲了。6.3 这套脚本的后续演进方向双脚本方案是能用、够用的底线不是终点。如果你接手了多套环境后续可以考虑几个方向的改造。一是参数化已经做了IP 通过命令行传入下一步可以把镜像仓库、Kubernetes 大版本号都抽成环境变量方便多环境切换。二是把公共部分sysctl、containerd 配置抽成一个真正的公共模块比如独立成common.sh供两个脚本 source避免改动一处两处不同步。三是如果你管理超过五台节点建议还是引入配置管理工具统一编排此时双脚本就从最终方案降级为初始原型但脚本里的所有逻辑依然可以作为工具的基础模块原样复用。我在实际项目中的体会是技巧很多时候并不在于命令本身而在于把整套流程想清楚后让一个全新的人也能照着脚本不假思索地复现集群。如果你也正准备搭一套 1.31 集群先从拷这两个脚本开始跑通一次之后再回头改参数基本就不会再想问为什么我的节点又 NotReady这种问题了。
说实话第一次自己动手搭 Kubernetes 1.31 集群的时候我还在老老实实一条条敲命令。一个 Master 加两个 Worker敲完内核参数、换源、装容器运行时、再初始化、配置网络插件一整套下来小半天就没了。更烦的是换一台机器、重装一次环境同样的命令又得从头来过错一个字符到后面排查起来就特别崩溃。后来我把这套流程沉淀成了两个脚本——一个初始化 Master一个初始化 Worker从此以后部署集群基本就是执行脚本 喝杯水的事。如果你也准备上手 Kubernetes 1.31或者不想把时间耗在重复的初始化命令上这篇文章就是给你准备的。我会把双脚本的拆分逻辑、每一步命令背后的原因、踩过的坑以及整个集群从执行到验证通过的过程全部拆开来讲。内容不追求高深但求每一步都清楚让你不仅能跑通还能知道为什么这样写。1. 为什么是双脚本Master与Worker的初始化差异决定了拆分边界先聊一个核心问题既然是快速部署为什么不直接写一个大脚本在每台机器上跑一遍很多人一开始都是这么想的但实际跑过就会发现Master 和 Worker 在集群里的职责完全不同初始化的动作差异非常大强行合并成一个脚本只会让逻辑越来越绕。Master 节点要做的事是生——生成集群。它需要承载控制面组件也就是 API Server、Controller Manager、Scheduler 和 etcd这些组件通过kubeadm init一次性拉起。Master 脚本里必须包含集群初始化动作执行完会生成证书、admin.conf 配置文件以及给 Worker 用的 join 令牌。而 Worker 节点的核心动作是入——加入集群也就是执行kubeadm join把当前节点注册进已有的控制面里。同一个脚本如果既包含 init 又包含 join脚本就必须去判断当前机器到底扮演什么角色判断条件越多出错的面就越大。再往细了看Master 初始化完成后还有一些收尾动作只有 Master 能做配置kubectl的访问凭证、安装 CNI 网络插件、生成 Worker 节点的 join 命令并保存到文件。这些动作放到 Worker 脚本里没有任何意义。反过来Worker 脚本需要做的事情则简单很多内核参数、容器运行时的部分可以复用同一段逻辑但集群初始化相关的代码完全不需要。双脚本方案的第二个好处是可控性。初始化集群是有顺序的必须先 Master 后 Worker而且所有节点在加入前Master 必须已处于 Ready 状态。脚本拆开之后执行顺序天然清晰先跑 Master 脚本跑完之后把生成的 join 指令带到 Worker 上跑 Worker 脚本就行。如果过程中某一步失败了你也能精准定位是哪台机器、哪个阶段的问题而不是在一个巨型脚本里从头到尾摸黑排查。还有一个容易被忽略的理由可维护性。Kubernetes 版本升级时Master 和 Worker 端的变更节奏往往不同步。版本升级时控制面的kubeadm init参数、CNI 版本、镜像地址可能需要单独调整而 Worker 侧通常只需要更新 kubelet、kubeadm 的版本。如果只有一个脚本每次升级都要在一个文件里反复腾挪很容易动一处伤另一处。拆开之后各自独立维护升级一个版本就是改两个文件里各自对应的那几行清晰得多。2. 动手写脚本前必须先敲定的四个关键决策脚本不是凭空写的。在我把命令落盘之前先花了半小时确定了几件非常重要的事这些决策直接影响脚本的稳定性和后续扩展性。2.1 版本锁定kubeadm、kubelet、kubectl 必须同一版本线Kubernetes 社区的版本策略是kubelet 版本必须小于等于 kubeadm 版本实操中为了省心最佳实践是让所有组件保持完全同版本。我这次部署用的是 1.31 版本线所以脚本里 kubeadm、kubelet、kubectl 安装时都要指定版本号而不是直接装 latest。如果装了不同版本的组合kubeadm init的阶段大概率会因为 API 版本不匹配而中断。这里我用的安装方式是 apt 源锁定版本。具体来说在/etc/apt/sources.list.d/kubernetes.list里配置好官方源之后用apt-cache madison kubeadm可以列出所有可用版本然后在安装命令里直接指定版本号外加hold操作防止意外升级apt-get install -y kubelet1.31.0-* kubeadm1.31.0-* kubectl1.31.0-* apt-mark hold kubelet kubeadm kubectl容器运行时我选择 containerd版本 1.7.x。这里有个关键配套动作containerd 和 Kubernetes 是通过 CRI 接口通信的版本上只要保证 containerd 官方支持 Kubernetes 1.31 即可不需要和 kubeadm 保持同一个版本号。我在生产实践中更推荐 containerd 而非 docker 作为运行时因为 containerd 更轻、CRI 兼容更直接不需要额外装 docker-shim。2.2 cgroup 驱动一律使用 systemd这是初始化容器运行时阶段最容易踩的坑。Kubernetes 从 1.21 开始建议 kubelet 与容器运行时使用 systemd cgroup 驱动而 containerd 2.x 的某些发行版默认配置仍然是 cgroupfs。如果两边驱动不一致kubelet 启动后大概率会报failed to run Kubelet: misconfiguration: kubelet cgroup driver: systemd is different from docker cgroup driver: cgroupfs。我的处理方式是在 Master 和 Worker 脚本里都加了一段 containerd 配置修正逻辑强制把/etc/containerd/config.toml里的SystemdCgroup设为truemkdir -p /etc/containerd containerd config default | sed s/SystemdCgroup false/SystemdCgroup true/ /etc/containerd/config.toml systemctl enable --now containerd这段命令的逻辑是先用containerd config default生成一份完整的默认配置再用 sed 替换关键行。注意不要自己在配置文件里手写有限几行配置containerd 的默认配置包含了很多重要的参数项直接覆盖会导致运行时行为异常。2.3 网络插件与 Pod CIDR我选了 Flannel 配 10.244.0.0/16Kubernetes 本身不提供 Pod 间网络初始化之后必须手动安装一个 CNI 插件否则节点状态永远是 NotReadyPod 永远调度不上去。主流的 CNI 有 Calico、Flannel、Cilium 等我这次选的是 Flannel理由很实际它是一个纯 overlay 网络方案部署最轻量配置文件直接 apply 就能用不依赖额外的数据面组件而且对实验环境、中小规模集群来说性能足够。代价是功能上比 Calico 少一些比如 NetworkPolicy 默认不支持。选择了 Flannel 也就确定了 Pod CIDR 必须使用10.244.0.0/16因为 Flannel 的默认配置文件里预设了这个网段。如果在kubeadm init时指定了别的 Pod 网段应用 Flannel 配置文件后会网段冲突点位之间完全不通。所以脚本里要写死kubeadm init \ --apiserver-advertise-address${MASTER_IP} \ --pod-network-cidr10.244.0.0/16 \ --kubernetes-version1.31.02.4 主机规划与前置检查时间同步、合理主机名、swap 关闭很多新手初始化失败的反而不是 kubeadm 本身而是基础环境不达标。kubeadm 的 preflight 检查非常严格任何一个条件不满足都会中断。我在脚本里内置了以下三项处理第一swap 必须关闭。Kubernetes 1.31 的 kubelet 默认还不支持启用 swap 的节点所以脚本里执行swapoff -a只是临时关闭还需要在 fstab 里注释掉 swap 条目保证重启后依然生效。第二时间同步必须做好证书校验强依赖时钟一致性我会在初始化之前确保 chrony 服务正常运行。第三主机名不能重复也不能包含下划线等特殊字符。两个 Worker 如果重名注册时节点会互相覆盖表现非常诡异。最好在跑脚本前手动设置好有区分度的 hostname。3. Master初始化脚本逐段拆解从内核调优到CNI安装一气呵成现在进入正式内容。我会把 Master 脚本的设计思路按执行顺序拆开每一段函数解决什么、为什么要这样写都会说清楚。这段脚本在初始化一个干净机器时可以直接复制使用但更建议你理解了之后再根据实际环境微调。3.1 预检与公共依赖安装脚本第一段是预检逻辑。因为是快速部署我不想让脚本跑到一半因为权限、缺依赖之类的问题失败所以预检写得很凶#!/usr/bin/env bash set -euo pipefail MASTER_IP${1:?Usage: $0 master_ip} POD_CIDR${POD_CIDR:-10.244.0.0/16} if [[ $EUID -ne 0 ]]; then echo 必须使用 root 账号执行本脚本 exit 1 fi # 关闭 swap 并注释掉 fstab 中的条目 swapoff -a sed -ri s/.*swap.*/#/ /etc/fstab # 加载内核模块 modprobe overlay modprobe br_netfilter cat /etc/modules-load.d/k8s.conf EOF overlay br_netfilter EOFoverlay模块是 containerd 的 overlayfs 存储驱动要用的br_netfilter则是让 iptables 能处理 bridge 流量Kubernetes 的 Service 转发依赖这个能力。只执行modprobe还不够万一重启后会丢失所以我在/etc/modules-load.d/k8s.conf里固化了下来。3.2 sysctl 参数设置让内核允许流量转发接着写 sysctl 配置。Kubernetes 节点需要开启 IP 转发并且要让 iptables 能看见 bridge 上的流量cat /etc/sysctl.d/k8s.conf EOF net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 EOF sysctl --system很多人会漏掉第一行。如果net.bridge.bridge-nf-call-iptables不设为 1从 Pod 发往 Service 的流量可能会在 bridge 层被绕过 iptables 规则导致 Service 负载均衡失效。这个参数在旧内核上是默认关闭的所以必须显式打开。不用纠结这些参数为什么这么难记这是 Kubernetes 官方文档 preflight 检查中的标准配置项照做就行。3.3 容器运行时与 kubeadm 工具链安装安装 containerd 和 kubeadm 工具链的代码占了脚本近一半的篇幅。这里我不推荐用发行版自带的 containerd版本更新滞后且配置路径不一致。我的做法是直接配置 docker apt 源来装 containerd然后通过 kubernetes apt 源装 kubeadm 全家桶apt-get update apt-get install -y containerd.io kubelet_install() { curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg echo deb [signed-by/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ / /etc/apt/sources.list.d/kubernetes.list apt-get update apt-get install -y kubelet1.31.* kubeadm1.31.* kubectl1.31.* apt-mark hold kubelet kubeadm kubectl }这里有个版本细节值得留意官方源目录结构里带了v1.31这个路径层级不同大版本对应不同的源目录。如果你的环境是 1.30 或 1.32源地址里的版本号也要跟着变否则 apt 会告诉你找不到安装包。3.4 集群初始化与kubectl配置工具链装好、containerd 配置完SystemdCgroup true之后就可以正式初始化集群了。我的脚本在 init 前加了一个状态判断避免重复执行时二次 initif [[ ! -f /etc/kubernetes/admin.conf ]]; then kubeadm init \ --apiserver-advertise-address${MASTER_IP} \ --pod-network-cidr${POD_CIDR} \ --kubernetes-version1.31.0 fi--apiserver-advertise-address必须指定为 Master 的局域网 IP也就是说脚本需要你传入一个参数不能写成0.0.0.0或 default。这决定了其他节点通过哪个地址访问 API Server写错了 Worker 将永远无法加入集群。初始化完成后/etc/kubernetes/admin.conf会生成管理员证书和访问配置。脚本接下来自动配置当前用户的 kubectlmkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config注意cp -i如果目标已存在会交互式询问是否覆盖。脚本模式里如果担心卡住建议改成cp -f。我自己实际用的时候改成了强制覆盖因为重复执行脚本本来就是为了最后一次配置生效。3.5 CNI安装与join命令落盘集群拉起后核心组件都处于 Running 状态但节点还是 NotReady因为没有任何一个 CNI 插件承担 Pod 网络。我直接用 kubectl 应用官方 Flannel 配置文件kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml关键一步来了。Worker 脚本需要执行的kubeadm join命令并不是凭空生成的它包含一个一次性令牌和 CA 证书的哈希指纹而这两样只有在 Master 初始化完成之后才会产生。所以 Master 脚本跑完之后我让它自动把 join 命令落盘保存存到一个固定路径kubeadm token create --print-join-command /root/k8s_join_cmd.sh chmod x /root/k8s_join_cmd.sh--print-join-command会直接输出一条完整的kubeadm join命令包括 token 和 CA hash。把这个内容重定向到文件后Worker 脚本可以从这个文件里读取并执行整个过程不需要手工复制任何信息。这个设计的细节我会在下一节里展开。4. Worker加入脚本逐段拆解Join凭证的获取与落地实现Worker 脚本的骨架和 Master 有约 60% 是重合的——预检、swap 关闭、内核模块、sysctl、containerd 安装、kubeadm 工具链安装这些都完全一致。这也是为什么我建议你把公共初始化逻辑抽出来或者在两个脚本之间复制保持一致。我在实际项目中其实是把公共部分直接复制到两个脚本里的因为它们会分别在各自节点上跑互相调用的依赖关系越少越好。4.1 Join命令的三种获取方式与最终选择Worker 脚本真正和 Master 不同的部分只在最后一段怎么拿到 join 命令并执行。这里我对比过三种方式第一种在 Master 上把/root/k8s_join_cmd.sh的内容通过 SSH 分发到 Worker。这种方式自动化程度最高但要求所有节点之间配置了免密登录对一台全新机器来说多了一层前置配置负担不够快速。第二种用配置管理工具如 Ansible 做统一分发、统一执行。这当然是最工程化的方案但会让双脚本变成双脚本配置管理工具三件套增加学习成本。对于个人实验或小规模集群有点重。第三种也是我最终采用的Worker 脚本接收 Join 命令文件路径作为参数或者更简单一点脚本里写死从同一个文件读取。实际部署时通过 USB、scp、文件共享或者任何顺手的工具把/root/k8s_join_cmd.sh传到 Worker 的对应路径即可。等 Worker 完成基础环境初始化后直接执行这个脚本文本。实际使用中我用了一个更省事的小技巧Master 脚本跑完后在最后几行把生成的 join 命令内容也一并输出到终端。这时候我只需要复制这行输出作为参数传给 Worker 的 join 脚本就行连文件传输都省了。所以 Worker 脚本里有一小段逻辑允许你把 join 命令作为字符串参数传进来JOIN_CMD${1:-$(cat /root/k8s_join_cmd.sh 2/dev/null)} if [[ -z $JOIN_CMD ]]; then echo 找不到 join 命令请从 Master 拷贝 /root/k8s_join_cmd.sh 的内容 exit 1 fi4.2 Worker脚本执行与状态确认当所有前置准备就绪Worker 脚本最终执行的就是这段eval $JOIN_CMD为什么用eval而不是bash $JOIN_CMD因为当 JOIN_CMD 是直接传进来的字符串参数时用bash执行需要先写入文件而eval直接在当前 shell 上下文执行适合这种场景。如果 JOIN_CMD 是从文件读的那两种写法等价。执行完 join 之后脚本还会做一次状态确认询问用户是否要在 Master 上检查节点状态echo Worker 已成功加入集群。可在 Master 节点执行: kubectl get nodes我用了一段简单的循环等待让脚本在 join 后持续检查 kubelet 是否存活直到输出active (running)或超时退出。这比直接打完命令就结束要可靠得多能第一时间发现因为版本不匹配、证书问题导致的 kubelet 启动失败。Worker 脚本的核心就这么简单。相比 Master 脚本的重Worker 脚本真正独有部分只有 join 凭证的获取和最终执行其余的都是在为这段服务。这也是为什么你会看到 Worker 脚本里同样完整地写了 sysctl 和 containerd 配置——缺少任何一部分kubelet 都无法在这个节点上正常拉起 Pod。5. 双节点实测从脚本执行到Pod跨节点通信的完整验证纸上谈兵到此结束。我拿一台临时环境做了完整实测两台虚机一台扮演 Master一台扮演 Worker。配置是 4C8G操作系统 Ubuntu 22.04 LTS内核版本 5.15。这个配置足够跑 Flannel 加几个测试 Pod。5.1 执行顺序与耗时的真实记录首先是 Master 节点。上传脚本后执行chmod x master_init.sh ./master_init.sh 192.168.31.10脚本执行耗时大约在 5-7 分钟时间大头全部花在 apt 安装和拉取镜像上。第一次看到 kubeadm init 输出的那一大串内容不要慌只需要关注最后几行。我实测中最后的输出里有这么一段关键信息Your Kubernetes control-plane has been initialized successfully!接着脚本自动执行完了 kubectl 配置和 Flannel 安装。我在 Master 上执行kubectl get nodes输出如下NAME STATUS ROLES AGE VERSION master-1 Ready control-plane 3m10s v1.31.0注意 STATUS 要在Ready状态。这中间有个时间差Flannel 的 Pod 要先拉镜像、启动然后节点才会从 NotReady 变 Ready。期间如果看到NotReady别急着排查等一两分钟再kubectl get nodes大概率已经恢复正常。接下来是 Worker 节点。我把 Master 上生成好的/root/k8s_join_cmd.sh拷贝到 Worker然后执行chmod x worker_init.sh ./worker_init.shWorker 脚本执行时间更短大概 3-4 分钟因为不需要拉控制面镜像。执行完后回到 Master再次查看节点状态kubectl get nodes NAME STATUS ROLES AGE VERSION master-1 Ready control-plane 15m v1.31.0 worker-1 Ready none 2m20s v1.31.0如果 Worker 一直处于 NotReady最常见的两个原因我留在下面的踩坑清单里说。5.2 部署测试Pod验证跨节点通信节点 Ready 不代表网络没问题。我用最简单的 Nginx Deployment 做了连通性测试副本数设置为 2这样两个副本大概率会被调度到不同节点上kubectl create deployment nginx --imagenginx --replicas2 kubectl rollout status deployment/nginx kubectl get pods -o wide看到两个 Pod 分别运行在 master-1 和 worker-1 上之后再验证跨节点访问。进入其中一个 Pod去 curl 另一个 Pod 的 IPkubectl exec -it pod-a -- curl pod-b-ip能返回 Nginx 页面说明两个节点上的 Pod 网络已经通了VXLAN 隧道正常Flannel 配置无误。这一步是整条链路最后的承重墙。如果这里不通问题会集中在 Flannel 的网段配置或者交换机对 VXLAN 流量的限制上排查思路和 Service 调不通完全不同。5.3 我踩过的几个常见坑与此解决方案部署过程中我特意复现了几个高频故障看看脚本是否能承受顺便记录下处理方式。第一token 过期。kubeadm 默认创建的 bootstrap token 有效期是 24 小时。如果生成的 join 命令放了超过一天没用Worker 执行 join 就会报 token 过期。解决方式是回到 Master 重新执行一次kubeadm token create --print-join-command把新命令传给 Worker。我的脚本里已经把这一步独立封装了所以临时加节点时不用重新初始化集群。第二主机名冲突。我有一次因为忘记设置主机名两台机器都叫 ubuntu结果 Worker 注册后Master 上的节点列表里只显示一个节点而且两个节点的名字互相覆盖。解决方法是分别在两台机器上执行hostnamectl set-hostname master-1和hostnamectl set-hostname worker-1然后重新 reset 并加入。第三版本不匹配。Worker 脚本里如果 apt 装到的是 1.31.1而 Master 初始化时用的是 1.31.0kubelet 和 kubeadm 的版本一般不会造成致命问题但 kubelet 与 API Server 的次版本差距超过一个版本时连接就会失败。这也是脚本里显式 lock 版本的原因。遇到这种情况时kubeadm reset后重新执行 Worker 脚本即可。6. 脚本沉淀后的扩展加节点、重跑与集群重置双脚本方案一旦跑通你接下来一定会遇到这几个场景集群扩容加 Worker、脚本因为故障需要重跑、整个环境推倒重建。这些场景不写进脚本里的话每次都会手忙脚乱。我把扩展思路一并写在最后。6.1 加新Workertoken过期后的快速处理新加一台 Worker 时Master 上原来生成的/root/k8s_join_cmd.sh大概率已经过期。不用重新跑 Master 脚本只要在 Master 上执行kubeadm token create --print-join-command拿到新命令后在 Worker 上直接执行即可。前提是 Worker 已经装好了 kubeadm、kubelet 这些组件。如果你复用了我上面的 worker_init.sh就会看到它已经支持把 join 命令字符串直接作为参数传入./worker_init.sh kubeadm join 192.168.31.10:6443 --token xxxxx --discovery-token-ca-cert-hash sha256:xxxxx这比重新拷贝文件再执行要顺滑得多。6.2 重跑脚本是否安全我的 Master 脚本本身是幂等的——只要admin.conf存在就跳过 init 直接走后续 kubectl 配置和 CNI 安装。但如果你真的想完全重来不能只靠重跑脚本要先销毁已有集群kubeadm reset -f rm -rf /etc/cni/net.d $HOME/.kube然后重新执行 Master 脚本。Worker 同理执行kubeadm reset -f后重新跑 worker_init.sh。如果你遇到节点状态异常想剔除旧节点在 Master 上用kubectl drain加kubectl delete node的标准流程也可以这个问题和脚本关系不大不展开讲了。6.3 这套脚本的后续演进方向双脚本方案是能用、够用的底线不是终点。如果你接手了多套环境后续可以考虑几个方向的改造。一是参数化已经做了IP 通过命令行传入下一步可以把镜像仓库、Kubernetes 大版本号都抽成环境变量方便多环境切换。二是把公共部分sysctl、containerd 配置抽成一个真正的公共模块比如独立成common.sh供两个脚本 source避免改动一处两处不同步。三是如果你管理超过五台节点建议还是引入配置管理工具统一编排此时双脚本就从最终方案降级为初始原型但脚本里的所有逻辑依然可以作为工具的基础模块原样复用。我在实际项目中的体会是技巧很多时候并不在于命令本身而在于把整套流程想清楚后让一个全新的人也能照着脚本不假思索地复现集群。如果你也正准备搭一套 1.31 集群先从拷这两个脚本开始跑通一次之后再回头改参数基本就不会再想问为什么我的节点又 NotReady这种问题了。
