刚用kubeadm部署完一套Kubernetes集群前后踩了不少坑但也把整个流程彻底理顺了。说实话kubeadm这套工具用熟了之后从零到一搭一套单Master、双Worker的基础集群一个下午就能收工。但你要是第一次接触里面每一环节都可能让人卡住镜像拉不下来、kubelet起不来、Node一直NotReady、Pod跨节点不通……这些都是新人必经的坎。这篇文章就把我最近一次从0到1用kubeadm部署k8s的完整过程记录下来从节点规划、系统初始化、容器运行时配置到Master初始化、Worker加入、网络插件安装最后再顺手验证一下跨节点调度和DNS解析。每一步都会说清楚“为什么这么做”而不只是贴命令适合刚学完K8s基础、想自己动手搭一套环境的人也适合想搞明白kubeadm原理的运维同学。1. 部署前的规划与关键选择1.1 为什么选择 kubeadm先聊一个大家都会纠结的问题部署K8s的方式那么多二进制、MiniKube、kubeadm、RKE、K3s为什么偏偏选kubeadmkubeadm是Kubernetes官方提供的集群初始化工具它的核心价值在于把“手动生成证书、配置控制面组件、生成kubeconfig”这些易出错的操作封装成了几条命令。它不是让你绕开K8s原理而是把证书、密钥、组件启动参数这些标准化了集群成员你可以用一条命令加进去后期想扩展成高可用也方便。二进制部署虽然可控性最强但要求你对每个组件的启动参数、证书路径、健康检查端口都了如指掌第一次搭的话光证书就可能折腾一整天。我这次自己搭环境时最看重的是kubeadm下面三点优势官方维护社区资料多报错搜解决方案容易。可以把初始化参数写进配置文件整套集群具备可复现性适合做交付文档。单节点到高可用集群升级路径相对平滑不用推翻重来。当然kubeadm也有短板比如它只负责把集群“启动”起来不等于给你做了生产化运维监控、日志、存储这些都得自己另外接。但对于想了解K8s内部构造或者搭建测试环境的人来说它仍然是最合适的起点。1.2 就绪检查与资源规划我这次用的是三台机器一个Master、两个Worker都是全新虚拟机操作系统统一用了Rocky Linux 9.3Kubernetes版本选了1.28.2。选1.28这个版本主要是因为它稳定发布有一段时间了同时还在官方支持窗口内。K8s版本迭代很快新版本可能有一些容器运行时兼容性的问题而老版本又可能过了维护期1.28目前算是一个比较平衡的选择。如果是自己练手建议最低配置按下面这张表来节点角色配置建议系统盘用途Master2C4G起步建议4C8G至少40G运行kube-apiserver、etcd等控制面组件Worker根据业务负载一般2C4G起至少40G运行业务Pod数据多的话需要额外数据盘这里要特别说一下etcd是集群的“数据库”读写频繁且依赖磁盘随机IO性能Master节点的磁盘千万别图便宜用普通机械盘至少也要SSD。像我们这次是纯测试环境机械盘也还能跑但如果打算长期使用SSD这块的预算不能省。1.3 网络与网段设计K8s集群内部有三种网络需要提前规划好Node网络物理机/虚拟机IP、Pod网络、Service网络。Node网络就是机器本身的IP这个大家都熟悉关键在Pod和Service网段。我在部署时选的Pod网段是10.244.0.0/16Service网段用K8s默认的10.96.0.0/12。这两个网段默认是内网私有网段但要求必须和你的物理机/虚拟机网段不重叠。比如你的机器IP是10.244.x.x那Pod网段还选10.244.0.0/16集群一跑起来路由就全乱了各种诡异的现象都会冒出来。Pod网段和Service网段选多大也要提前想清楚。10.244.0.0/16按/24切分每个节点可以分配出来256个Pod地址对于中小规模集群完全够用。如果你的Pod数量特别大或者未来可能扩容到几千个节点就要考虑更大的网段比如10.0.0.0/16这类。Service网段相对小一点没关系因为Service数量远少于Pod数量但也要留出余量。2. 所有节点的系统初始化2.1 主机名与hosts解析不管是什么节点先把主机名设置好。实践中最容易踩的坑是大家图省事直接让Node之间用IP互相访问结果Pod网络插件一装各节点通过主机名解析不到对方报错日志里全是未知主机名。我一般按角色来命名比如Master叫k8s-master-01两个Worker叫k8s-worker-01、k8s-worker-02。设置之后立刻改/etc/hosts把三台机器IP和主机名的映射写进去因为后面kubeadm init生成的证书、kubeadm join用的地址解析都会涉及主机名。hostnamectl set-hostname k8s-master-01 cat /etc/hosts EOF 192.168.100.10 k8s-master-01 192.168.100.11 k8s-worker-01 192.168.100.12 k8s-worker-02 EOF这里有个容易被忽视的点/etc/hosts的映射要写实际业务网卡的IP别把节点管理网卡的IP写上去。如果一台机器上有多个网卡比如有MaaS网卡和业务网卡K8s组件默认会选择第一个网卡地址到时候组件监听地址和你预期的不一致排查起来相当费劲。2.2 关闭交换分区与防火墙K8s官方要求必须关闭swap这点几乎人人知道但很多人不知道为什么。简单说Kubelet在计算节点可用内存时如果发现存在swap它无法准确判断Pod实际能用的内存量反而可能导致内存过载。所以在集群里运行时swap对K8s来说弊远大于利生产环境一律关闭。swapoff -a sed -i /swap/s/^/#/ /etc/fstabswapoff是临时关闭重启后又会挂载回来所以一定要同步注释掉/etc/fstab里对应的行否则重启之后Kubelet又会因为检测到swap而拒吃工作。防火墙这一块如果你是刚搭测试环境最简单粗暴的方式是先把firewalld关掉。k8s各个组件之间有大量的端口通信需求新手期开着防火墙十有八九会漏放端口建议先把环境跑通再回去根据官方文档里的端口清单做收敛。systemctl disable --now firewalld我建议同时把SELinux也改成permissive模式。在高安全要求的场景下SELinux可以保留但K8s相关操作在SELinux enforcing下很容易触发权限问题测试环境不用折腾它直接setenforce 0并修改/etc/selinux/config保持永久生效。2.3 内核参数与模块配置这一步做的人多但很少有人讲清楚原因。K8s的核心网络转发依赖一些内核模块和网络参数你不配好后面Pod网络怎么都跑不通。需要加载的内核模块主要是br_netfilter和ip6table_filter。br_netfilter的作用是让桥接的流量也经过iptables规则的过滤K8s的Service转发、NodePort访问都依赖iptables/ipvs规则这个模块不加载流量转发就会出问题。cat EOF | tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF modprobe overlay modprobe br_netfilter光加载模块还不够还要设置sysctl参数核心就三个net.bridge.bridge-nf-call-iptables、net.ipv4.ip_forward、net.bridge.bridge-nf-call-ip6tables。其中net.ipv4.ip_forward尤其重要它负责开启当前节点的IP转发能力Pod跨节点通信依赖的就是节点转发数据包不开启的话转发链路上直接丢包。cat EOF | tee /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 EOF sysctl --system有个小习惯我建议保留每改完内核参数都用sysctl --system检查一遍有没有报错然后查一下lsmod | grep br_netfilter确认模块确实加载了。很多情况下你觉得配了其实配置文件路径写错或者模块名写错静默失败到后边网络出问题才追悔莫及。2.4 安装容器运行时 containerd容器运行时这块我直接用了containerd 1.7.x没有用Docker。原因很简单Kubernetes从1.24版本开始已经完全不支持Docker作为运行时了它只支持符合CRI标准的运行时而containerd就是那个最主流的选择。用包管理器装其实很省事以Rocky/RHEL系为例dnf install -y containerd.io装完之后先别急着启动先改配置。这步是新手重灾区直接不改也能起但会有两个大问题一是cgroup驱动不是systemd和Kubelet的默认配置对不上二是它默认去拉registry.k8s.io/pause镜像在国内网络环境下大概率会超时。先通过下面的命令生成默认配置mkdir -p /etc/containerd containerd config default | tee /etc/containerd/config.toml然后修改两个关键点。在[plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc.options]下设置SystemdCgroup true让containerd统一使用systemd作为cgroup驱动和Kubelet保持一致。第二个是修改sandbox_image为可访问的pause镜像地址。这一步在离线或者网络受限环境里非常重要你把它指向你内网镜像仓库里的pause镜像即可否则CNI插件装完后Pod全部卡在ContainerCreating。systemctl daemon-reload systemctl enable --now containerd systemctl status containerd启动后建议用ctr version看看版本确认服务正常。另外再强调一个细节containerd默认的/opt/containerd和/var/lib/containerd目录尽量放在数据盘上尤其Pod多了以后镜像和容器层占用的空间增长非常快。3. 安装 kubeadm、kubelet、kubectl3.1 配置仓库源与版本选择K8s组件的安装源需要单独配置这里面的坑在于如果你直接用云厂商的公共镜像源有些源的默认包版本可能不是你自己想要的。比如你之前已经规划好要装1.28.2结果直接yum install kubeadm给你装了个1.29.x后面你的教程全部要对不上了所以版本一定要显式指定。我这边习惯在每一个节点上统一配置官方源或某个镜像站然后锁定版本安装。配置源的时候注意区分RHEL系和Debian系命令本质是一样的就是写仓库文件。仓库文件的内容大概是定义好baseurl指向你的软件源地址然后导入GPG key。cat EOF | tee /etc/yum.repos.d/kubernetes.repo [kubernetes] nameKubernetes baseurlhttps://mirrors.xxx.com/kubernetes/yum/repos/kubernetes-el9-x86_64/ enabled1 gpgcheck0 repo_gpgcheck0 EOF dnf makecache源配好之后用dnf list available kubeadm --showduplicates查看该源提供的可用版本列表确认一下1.28.2确实存在。这一步千万不能忽略很多人栽在“明明配好了源安装时却提示找不到版本”上面很可能就是源的版本目录和你系统版本不匹配比如你是el9系统却配了el7的源。3.2 安装组件与锁定版本安装时三个组件要一起装、版本要一致。kubelet、kubeadm、kubectl如果版本不一致虽然集群往往也能跑起来但后续排查问题的时候你会发现各种困惑比如kubectl版本太新连不上老版本的API Server。dnf install -y kubelet-1.28.2 kubeadm-1.28.2 kubectl-1.28.2装完以后有个附加操作很重要加锁版本防止以后执行系统级更新时被意外升级。K8s组件跨版本升级不是小事多了一个自动升级的隐患多不值得直接把update策略改成excluded或者通过包管理器将版本锁住。dnf versionlock add kubelet-1.28.2 kubeadm-1.28.2 kubectl-1.28.2安装完成后kubelet会被自动装上但还没启动。这里给第一次接触的人打个预防针现在就算你手动启动kubelet它也会处于反复重启的异常状态日志里全是“找不到静态Pod”之类的报错这是正常的因为kubelet必须在集群初始化后才知道自己要做什么。你只需要先把服务设置成开机自启。systemctl enable --now kubelet3.3 配置crictl工具这里要顺带提一个我摸索出来的习惯装完containerd后顺手把crictl也装上这是社区提供的CRI命令行工具用来查看容器状态。其实在K8s环境中排查问题crictl ps比docker ps好用得多因为它是通过CRI接口直接看Kubernetes视角的容器状态能看到sandbox容器和业务容器。dnf install -y cri-toolscrictl默认连接的endpoint可能是老的Docker socket路径而我们用的是containerd所以要配置一下连接地址。编辑/etc/crictl.yaml把runtime-endpoint指向unix:///run/containerd/containerd.sock。配置好后先执行crictl info验证连通性这一步通过了后面遇到Pod起不来的问题你可以先看crictl ps -a快速定位容器没起来的原因。4. 初始化 Master 节点4.1 编写 kubeadm 配置文件kubeadm init虽然可以直接用命令行参数执行但我强烈建议你写成配置文件。理由很简单命令行参数是一次性的你无法直观看到所有配置而配置文件可以提交到git里保存以后升级或者重建集群直接改改就能复用这才是可运维的方式。# kubeadm-config.yaml apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: 192.168.100.10 --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: 1.28.2 networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 imageRepository: registry.example.local/google_containers controlPlaneEndpoint: 192.168.100.10:6443配置文件里advertiseAddress是采用本机的业务IP也就是各节点能互相访问的那个IP。podSubnet和serviceSubnet必须和你在前面规划的一致不能随意改。controlPlaneEndpoint是高可用场景下使用的虚IP单Master时写Master本身IP即可。imageRepository是大家在新手期最容易卡住的点相关命令默认从国外镜像仓库拉取国内环境成功率很低改成你内网镜像仓库或加速镜像站是基本操作。4.2 执行 init 并处理镜像问题在执行kubeadm init之前我习惯先预拉取镜像把可能报错提前暴露出来kubeadm config images pull --config kubeadm-config.yaml如果这一步报错大概率是在镜像地址上。可以先看错误信息里显示的是哪个镜像地址然后手动用crictl pull该地址的镜像测试连通性。把镜像仓库地址换成一个可访问的镜像站或者通过离线包导入镜像都能解决。拉取镜像没问题后正式执行初始化kubeadm init --config kubeadm-config.yaml --upload-certs整个初始化过程持续两到三分钟中间你会在日志里看到证书生成、控制面组件启动、etcd健康检查通过等步骤。初始化成功后日志末尾会显示三块信息如何配置kubeconfig、如何安装CNI网络插件、如何让Worker加入集群。强烈建议把这段输出完整保存下来特别是最后一个join命令省得回头又要去重新生成。执行完kubeadm init后紧接着配置kubectl。按输出提示操作mkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config然后先检查一下集群和控制面组件的状态kubectl get nodes kubectl get pods -n kube-system此时Node状态大概率是NotReady这完全正常因为CNI网络插件还没装。K8s就是这样控制面组件起来了但没有网络插件节点之间没法建立Pod网络所有Pod会处于Pending或者CrashLoopBackOff状态。4.3 安装CNI网络插件CNI插件我选的是Calico这也是目前K8s生产环境最主流的网络方案。Calico支持BGP、IPIP等方式功能上能覆盖网络策略控制性能在中小规模集群上表现也很稳。如果你只是想快速跑通环境Flannel也是一个选择它更简单但功能比Calico少很多。Calico的YAML清单一般是从它的发布维护仓库下载下载之后先别急着直接应用最关键的一步是把里面的CALICO_IPV4POOL_CIDR改成你在初始化时定的Pod网段比如10.244.0.0/16。默认Calico清单自带的通常不是这个网段你不改的话Calico的Pod网段和集群设计对不上Pod分配不到可用的IP。curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml kubectl apply -f calico.yamlCalico安装完成后kubectl get pods -n kube-system里会多出一组calico-*的Pod。等这些Pod全部转成Running差不多一两分钟再看节点状态kubectl get nodes -o wide这里有个经验如果Calico持续有一两个Pod一直Init:0/1或者CrashLoopBackOff九成问题是节点上的/etc/cni/net.d/目录里已经有其他配置文件残留或者Pod网段和节点IP网段冲突。遇到这种情况先查看Calico Pod日志里的具体报错内容再决定怎么改。5. Worker 节点接入集群5.1 生成加入集群的命令Master节点初始化成功后Worker节点加入集群用的是kubeadm join命令。本质上它要解决两件事一是身份认证证明你有权限加入二是获取集群的证书信息和API Server建立信任关系。如果前面没有保存初始化输出可以重新生成一个join命令kubeadm token create --print-join-command这个token默认有效期24小时你可以顺手加一个--ttl 4h之类的参数自定义有效期。其实如果你需要在多个Worker上复制命令最简单的方式是把这个输出直接写成一段shell脚本然后依次到每台Worker上执行。如果token过期了重新生成即可不用重新初始化集群。5.2 在Worker节点上执行加入操作到Worker节点上先确认提前完成了系统初始化、containerd安装和kubelet安装然后执行join命令kubeadm join 192.168.100.10:6443 --token xxxxx --discovery-token-ca-cert-hash sha256:xxxxxxxx这个过程一般一分钟以内完成。执行成功后会提示This node has joined the cluster这时回到Master上执行kubectl get nodes刚加入的Worker节点同样会先显示为NotReady这是它在等待CNI网络配置下发。如果一两分钟后还是NotReady优先用journalctl -u kubelet -f实时查看kubelet日志排查。5.3 端到端验证跨节点Pod集群加入完成后做一轮实际验证很有必要。很多人以为节点变成Ready就够了其实节点Ready只代表组件健康不代表业务流量能通。我习惯直接部署一个Nginx测试应用让它跨节点调度验证Pod之间互通和服务访问。先创建一个简单的Deployment和Servicekubectl create deployment nginx-test --imagenginx:1.25 --replicas2 kubectl expose deployment nginx-test --port80 --typeNodePort kubectl get svc nginx-test kubectl get pods -o wide从输出里你可以直观看到两个Pod分布在不同节点上Service也分配了ClusterIP和NodePort。这时去浏览器或命令行访问任意节点IP加NodePort端口能访问到Nginx页面说明网络链路已经通了。再做一次跨节点通讯检查进到其中一个Pod里去ping另一个Pod的IPkubectl exec -it nginx-test-xxxx -- bash ping 10.244.1.3能通的话跨节点网络就没有问题了。最后再验证一下DNSkubectl exec -it nginx-test-xxxx -- bash nslookup nginx-test能解析出Service的ClusterIP说明CoreDNS工作正常。到这一步整条k8s部署链路就验证完毕了。6. 常见问题定位与排查6.1 问题速查表把这次实践中最典型的坑点整理成一张速查表方便大家对照排查现象常见原因定位思路kubelet服务反复重启缺少静态Pod配置或cgroup驱动不一致journalctl -u kubelet -f看报错初始化时报错failed to pull image...镜像仓库不可达或仓库地址写错kubeadm config images pull验证Node长时间NotReadyCNI插件没装、网络网段冲突查看kube-system下对应Pod日志Pod一直Pending节点资源不足、镜像拉取失败kubectl describe pod查看事件初始化成功但kubectl无权限kubeconfig没配置好检查~/.kube/config是否存在跨节点Pod不能互访firewalld没关、sysctl转发未开启检查ip_forward、iptables规则排查问题的时候一定要学会一个顺序先看kubelet日志再看Pod事件最后看具体容器日志。绝大多数问题都能通过这个顺序定位到根因不要一上来就到处翻文档。6.2 三类重点坑与排查方法第一类kubelet一直起不来的问题。这是新手最多遇到的坑。systemctl status kubelet显示active但很快退出日志里最常见的报错是failed to run Kubelet: misconfiguration: kubelet cgroup driver: systemd is different from docker cgroup driver: cgroupfs。解决方式很简单把containerd配置文件里SystemdCgroup设为true或者在kubelet配置里指定cgroup驱动。我建议直接统一用systemd修改好containerd配置后重启containerd和kubelet。第二类节点状态一直是NotReady。造成这个问题的原因比较多但最隐蔽的是Master节点上的/etc/hosts没有正确配置到Worker节点的主机名。CNI Agent启动时如果解析不了各节点的主机名网络插件就会处于半初始化状态。可以先把所有节点的主机名和IP写进每个节点的/etc/hosts然后观察kubectl get nodes是否恢复Ready。第三类初始化时证书哈希不匹配。执行kubeadm join时如果不小心改了token中的哈希值或者使用了过期的token会报CA certificate hash mismatch。重新在Master上执行kubeadm token create --print-join-command拿到新的join命令再来执行就行不用重新初始化集群。6.3 日常维护与续期问题集群搭好以后还有一个很多人会忽略的问题证书有效期。K8s控制面组件的证书默认有效期一年到期之前需要续期。kubeadm在这个场景里提供了很大的便利一年之内执行kubeadm certs renew all即可续签所有证书续签之后重启控制面组件即可生效。为了防止你忘记这件事我建议装一个监控或者定时任务在证书快过期时提醒一下自己。检查当前证书过期时间可以用kubeadm certs check-expiration这个命令会列出每张证书的剩余时间一目了然。或者简单一点直接在日历上标注好下次续期时间一年一提醒虽然粗暴但比忘了好。另外日常查看集群状态的时候我习惯用这几条命令kubectl get nodes -o wide kubectl get pods -A -o wide | grep -v Running journalctl -u kubelet --since 1 hour ago --no-pager | tail -n 50这三条命令一次执行节点健康、异常Pod、kubelet日志全覆盖日常巡检够用了。最后再说一个个人体会用kubeadm部署k8s最大的价值不是“把命令跑通”而是你在处理各种报错的过程中把K8s的组件构成、网络模型、证书体系都摸了一遍。我建议你部署完后把初始化配置文件、CNI清单、加入命令这些关键资产全部整理到文档或git仓库里下次重建集群就不用再从头摸石头过河了。环境跑起来只是开始能把集群管住、把问题定位清楚那才是真正的收获。