Kubeadm搭建K8s单Master集群完整指南

这两年容器编排基本成了后端团队的标配Kubernetes 更是绕不开的那个关键词。我在本地环境和云服务器上都折腾过好几轮集群从kubeadm init报错一头雾水到后来能熟练处理各种证书过期、网络插件冲突的坑踩过的雷不算少。这篇就以“k8s单master集群搭建”为主线把从零到一的过程完整拆开讲包含环境规划、组件选择、初始化参数、加入工作节点以及常见故障排查。目标很直接照着走能搭出一套稳定的单控制面集群同时让你明白每一步为什么要这么做遇到问题知道从哪里下手。先说清楚适用对象想自己动手学习 Kubernetes 原理的开发者或者刚接手内部测试环境、想快速起一套集群的人。单 master 架构虽然不具备高可用能力但对学习、开发、测试、演示来说完全够用资源占用也比多控制面集群小得多。1. 整体架构与版本选型为什么从单 Master 开始1.1 控制面组件拆解Kubernetes 集群从角色上分两类节点控制平面节点和工作节点。单 Master 集群就是只有一台机器承担全部控制面组件剩下的机器作为工作节点运行业务负载。控制面核心组件包括kube-apiserver所有组件通信的中枢外部请求kubectl、API 调用也走它相当于整个集群的“入口网关”。kube-controller-manager负责维持集群期望状态比如副本数不够就补 Pod节点掉线就标记状态。kube-scheduler决定新建的 Pod 落在哪个节点上会根据资源余量、亲和性、污点等条件做调度决策。etcd集群所有数据的存储后端状态、配置、资源对象都存在这里面是整个集群的“数据库”。单 Master 部署的核心特征是“控制面和数据面都在一台机器上”但工作节点的 kubelet、kube-proxy、容器运行时都是独立运行的。这个结构清晰适合理解 Pod 调度和组件通信链路。先把单控制面的链路吃透后续再过渡到 HA 集群或托管集群时很多概念就能直接复用。1.2 版本与运行时选型依据搭建前最重要的一件事是统一版本。Kubernetes 迭代很快小版本升级带来的 API 变化、特性开关差异都可能成为集群不稳定的诱因所以控制面、工作节点、kubeadm、kubectl 这些组件的版本最好保持一致。我常用的组合是组件版本说明Kubernetes1.28.x稳定、支持周期内资料也丰富容器运行时containerd 1.7.x稳定、资源占用适中当前主流选择操作系统Ubuntu 22.04 / CentOS 7.9 / Rocky 9内核版本高一点更稳kubeadm / kubelet / kubectl与集群版本一致避免版本不匹配的坑CNI 插件Calico 3.27 / Flannel按网络需求选择容器运行时我没有选 Docker 的原因是Kubernetes 从 1.24 版本开始移除了对 Docker 的直接支持虽然可以通过 cri-dockerd 桥接但 containerd 本身就是为 CRI 设计的链路上少一层转换性能更好排障也更直接。这里说的“移除支持”不是不能用了而是 kubelet 不再直接调用 Docker API需要额外适配器对学习和新环境来说没有意义直接用 containerd 才是正路。1.3 网络模型与网段规划Kubernetes 对内网段规划有两块必须提前想清楚Service 网段和 Pod 网段。这两个网段不能与宿主机现有网段冲突否则会出现路由异常、Pod 无法访问等诡异问题。我在实验环境里常用的规划如下节点网段192.168.1.0/24宿主机局域网Pod 网段10.244.0.0/16分配给 Flannel 网段Service 网段10.96.0.0/12kubeadm 默认就是它如果局域网规划比较拥挤可以调整 Service 网段但要注意 Pod 网段必须和 CNI 插件的默认值对齐。以 Flannel 为例它的默认网段就是10.244.0.0/16你不加参数它会按这个来所以初始化时--pod-network-cidr10.244.0.0/16和 Flannel 默认值的一致性是最省心的。注意规划好之后整个集群生命周期内尽量不要再改网段。改网段的代价基本等于重建集群特别是已有业务数据时非常痛苦。2. 环境准备与组件安装两个容易埋雷的环节2.1 系统基础配置不管用哪套 Linux 发行版有三项基础配置是绕不开的主机名解析、时间同步、内核模块。看起来简单没做好后面会埋不少坑。我一般按这个顺序处理设置主机名。控制面节点用k8s-master工作节点用k8s-node1、k8s-node2这类清晰命名。同时改/etc/hosts把集群内所有节点的 IP 和主机名对应关系写进去保证节点之间可以互相解析。kubeadm 生成证书时依赖主机名和 IP 的对应关系解析不通会导致初始化失败或者节点加入异常。安装时间同步。推荐chrony或systemd-timesyncd任选其一。集群内证书校验依赖时间一致时间偏差超过五分钟组件间的 TLS 握手就会出现证书有效性错误kubeadm init时经常看到x509: certificate has expired or is not yet valid这类报错。很多新手会误以为是证书本身出了问题实际上就是时钟没对准。关闭 swap。这个其实是 kubelet 的默认要求虽然新版 kubelet 支持开启 swap 运行默认还是需要关掉。刷不刷swapoff -a可能直接影响kubeadm init是否能通过预检。加载内核模块关键是br_netfilter并调整net.bridge.bridge-nf-call-iptables等内核参数确保 iptables 能正确处理桥接流量。用了这么多年 Linux 的经验是尽量把这类初始化做成脚本存到本地配置仓库里遇到新环境直接跑一遍避免反复手工操作漏掉步骤。2.2 containerd 安装与配置要点容器运行时我选的是 containerd安装方式取决于你的发行版。Ubuntu 可以用官方源CentOS 系用 yum 源核心是装完之后要生成一份调整好的配置文件。# 生成默认配置然后修改 containerd config default | sudo tee /etc/containerd/config.toml /dev/null生成配置后有两个必须改的点第一个是镜像加速器。国内拉取registry.k8s.io的镜像经常会超时所以需要把 sandbox 镜像地址或者整个 registry 配置成可用镜像源。具体配置参考你所在网络环境能访问的源不同地区选择不同不要照搬网上的域名。第二个是SystemdCgroup参数。containerd 默认使用 cgroupfs 作为 cgroup 驱动而 kubelet 默认期望 systemd 驱动二者不一致会导致节点状态一直NotReady。所以要把配置里的SystemdCgroup设为true。[plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc] [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc.options] SystemdCgroup true注意如果你改动了 containerd 的配置务必systemctl restart containerd。改完配置忘了重启是所有新手最容易踩的坑restart 之后ctr version验证一下再继续。2.3 kubeadm / kubelet / kubectl 安装这组组件只能用 k8s 官方源安装不能用系统自带的旧版本。发行版用 yum 或 apt 添加官方源之后安装指定位版本。# Ubuntu apt-get update apt-get install -y kubelet1.28.2-00 kubeadm1.28.2-00 kubectl1.28.2-00 # CentOS/Rocky yum install -y kubelet-1.28.2 kubeadm-1.28.2 kubectl-1.28.2安装完不要急着启动 kubelet。此时集群还没初始化kubelet 会不断尝试连接 apiserver 但连不上状态会一直处于异常或反复重启这是正常现象。先设置systemctl enable kubelet但不要执行systemctl start kubelet。等kubeadm init完成后kubelet 自然会由 kubeadm 拉起来。版本一致性是集群的“潜规则”。控制面版本如果比节点版本新节点可能被拒绝注册反过来旧版本节点虽然能注册但很多 API 对象处理起来会有兼容问题。最稳妥的做法是集群内所有 k8s 组件版本完全一致。3. 控制面初始化kubeadm init 全流程3.1 预检与初始化命令核心命令是kubeadm init但参数需要在动手前确认清楚。以下是我在单 Master 集群中常用的完整初始化命令kubeadm init \ --apiserver-advertise-address192.168.1.10 \ --control-plane-endpoint192.168.1.10 \ --image-repositoryregistry.cn-hangzhou.aliyuncs.com/google_containers \ --kubernetes-versionv1.28.2 \ --pod-network-cidr10.244.0.0/16 \ --service-cidr10.96.0.0/12参数含义逐个说清楚--apiserver-advertise-addressapiserver 对外公布的地址控制面节点自身的 IP。如果机器有多个网卡必须显式指定否则 kubeadm 可能选错网卡。--control-plane-endpoint高可用场景下是负载均衡器地址单节点时填同一个 IP 就行。--image-repository镜像仓库地址。默认是registry.k8s.io国内网络经常拉不动换一个可用仓库可以避免卡在kubeadm init拉镜像阶段。--kubernetes-version明确指定版本避免默认版本与 kubelet 不一致。--pod-network-cidrPod 网段与 CNI 插件默认网段对应。--service-cidrService 网段不指定默认就是10.96.0.0/12。执行前可以先跑kubeadm config images pull用同一组参数把镜像先拉下来避免在 init 过程中因拉镜像超时中断。镜像都本地就绪后再跑 init 会快很多。3.2 初始化过程中的常见阻断点kubeadm init失败最常见的原因集中在预检阶段preflight。我遇到过并实际解决过的错误主要有端口被占用。6443、10250、2379、2380这些端口被其他进程占用kubeadm直接拒绝继续。先ss -lntp查端口占用能换个端口就换不能换就停掉冲突服务。swap 未关闭。提示running with swap on is not supported执行swapoff -a并注释掉/etc/fstab里的 swap 行防止重启后 swap 又自动挂回来。容器运行时 sock 找不到。kubeadm 默认会扫描/var/run/containerd/containerd.sock你没启动 containerd 或者配置路径不对预检直接失败。确保 containerd 服务状态正常。版本不匹配。比如 kubeadm 是 1.28 但指定--kubernetes-versionv1.27.3预检会报版本不一致。这时候要么统一 kubeadm 版本要么让版本参数跟组件一致。3.3 初始化成功后的输出信息当kubeadm init最后输出Your Kubernetes control-plane has initialized successfully!这时候意味着控制面组件已经全部起来了。这段输出信息很大保存好三个关键部分第一是给管理员用的 kubeconfig 配置命令。默认情况下只有 root 能直接访问集群普通用户需要把配置文件拷到自己的目录mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config第二是工作节点加入集群的指令形如kubeadm join 192.168.1.10:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx这条命令有效期为 24 小时如果过期了可以重新生成 token后面详细讲。第三是 kubeconfig 文件的位置。管理集群所有操作的入口就是/etc/kubernetes/admin.conf这个文件要备份好一旦丢失意味着你失去了对集群的管理权限。初始化成功之后立刻验证控制面状态kubectl get nodes此时 master 节点状态大概率是NotReady别慌原因有两层一是 CNI 网络插件还没装节点上的 Pod 网络就不通二是 kubelet 要等网络就绪后才会把节点状态标记为 Ready。继续下一步即可。4. 容器网络插件安装Flannel 还是 Calico4.1 网络插件选型对比CNI 插件是 Kubernetes 集群里跳过就直接瘫痪的一环。安装之前先确定选型不同插件对初始化参数的依赖完全不同。我实际用过两者简单对比维度FlannelCalico网络模式VXLAN / host-gwBGP / VXLAN / IPIP网络策略不支持支持完整 NetworkPolicy性能中规中矩BGP 模式下性能更好部署复杂度简单稍复杂依赖 etcd 存储适用场景学习、测试、小型内部环境生产环境、需要网络策略的场景单 Master 学习环境优先推荐 Flannel原因很实际部署最简单默认网段和kubeadm init参数保持一致装完就能用。如果后续要学 NetworkPolicy 或者模拟生产环境网络隔离可以换 Calico。换插件之前要先删掉已有的 Flannel DaemonSet否则新旧插件抢 iptables 规则网络会变得一团糟。4.2 Flannel 安装流程Flannel 安装本质就是创建一个 DaemonSet让每个节点上自动运行 flanneld 进程。下载官方 manifest 文件然后 apply 即可wget https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml kubectl apply -f kube-flannel.yml这里有个必须注意的点下载下来后要确认 manifest 里的Network字段是否为10.244.0.0/16如果你的--pod-network-cidr参数改了必须同步改 manifest 里的网络段否则 flanneld 和 kube-controller-manager 分配的 Pod CIDR 对不上跨节点 Pod 通信会直接断掉。我实际遇到过一种情况manifest 下载没问题apply 也成功但 Pod 都是CrashLoopBackOff。查看 flanneld 日志发现是Network 10.244.0.0/16 does not match the existing interface subnet。原因就是节点上之前手动创建了 docker 网桥或者其他虚拟网卡把网段占用了。这种环境干净的机器反而少踩这种坑。安装完成后验证kubectl get pods -n kube-flannel等到所有 flannel Pod 都Running再查看节点状态kubectl get nodes正常情况下 master 节点会从NotReady变成Ready。如果还卡在NotReady大概率是 kubelet 的 cgroup 驱动跟 containerd 不一致回到上一节检查SystemdCgroup配置再重启 containerd 和 kubelet。4.3 网络插件安装后的验证节点 Ready 只是第一步还需要确认控制面核心服务状态kubectl get pods -n kube-systemkube-apiserver、kube-controller-manager、kube-scheduler、etcd这几个 Pod 都应该是Running。同时确认coredns是否 RunningDNS 组件不工作的话集群内服务发现全废。做个最简单的连通性验证kubectl run nginx-test --imagenginx --port80 kubectl expose pod nginx-test --port80 --namenginx-test-svc kubectl run --rm -it test-pod --imagebusybox -- /bin/sh # 在容器内执行 wget -O- http://nginx-test-svc:80能访问就说明 Pod 间通信、Service 转发、DNS 解析都正常集群的核心链路已经通了。5. 工作节点加入与多节点验证5.1 节点加入前置条件工作节点加入前环境准备和控制面节点完全一致需要安装 containerd 并配置 cgroup、安装 kubelet 和 kubeadm、关闭 swap、加载内核模块。不要偷懒跳过这些步骤我见过只装 kubelet 就执行 join 的结果 kubelet 不断重启节点一直处于NotReady。准备好以后在工作节点执行控制面初始化时输出的 join 命令kubeadm join 192.168.1.10:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx正常情况下会输出This node has joined the cluster: * Certificate signing request was sent to apiserver and a response was received. * The kubelet was informed of the new secure connection.回到控制面节点运行kubectl get nodes节点STATUS只要变成Ready就是加入成功了。5.2 Token 过期与重新生成之前说过 join token 有效期是 24 小时。如果初始化后隔了几天才想起加节点或者 token 被误删了不要重新初始化控制面直接重新生成kubeadm token create --print-join-command它会生成新的 token 和对应的--discovery-token-ca-cert-hash拿这条新命令去节点上 join 即可。还有一种情况需要留意如果控制面节点的证书也换了比如重新生成过 CA 证书那 hash 也会变。稳妥的做法是先执行openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2/dev/null | openssl dgst -sha256 -hex | sed s/^.* //重新计算 CA 的 hash 值。5.3 单 Master 集群的调度限制单 Master 集群默认情况下 master 节点不让跑业务 Pod因为初始化时会给 master 节点打上污点node-role.kubernetes.io/control-plane:NoSchedule。如果集群一共就两台机器master 不让调度负载资源就浪费了一半。这时候有两种选择第一种是用上 tolerations 的方式专门为需要跑在 master 上的 Pod 加容忍。比如我想在 master 上跑监控组件tolerations: - key: node-role.kubernetes.io/control-plane effect: NoSchedule第二种是直接移除 master 的污点让所有业务 Pod 都能调度到控制面节点kubectl taint nodes k8s-master node-role.kubernetes.io/control-plane-这个操作在生产环境不推荐但在单 Master 学习和测试环境中很实用。我个人一般保留污点然后给特定 DaemonSet 或关键组件显式加容忍这样更贴近真实生产习惯。6. 常见故障与排查实录6.1 节点处于 NotReady 状态节点 NotReady 是集群排障遇到最多的状态原因集中在几个方面。第一是 kubelet 没起来。在生产里我总结出一条排查命令组合systemctl status kubelet journalctl -u kubelet -f日志里如果反复出现failed to connect to http://localhost:10248/healthz说明 kubelet 本身没有成功注册先看 containerd 是否健康、cgroup 驱动是否匹配。第二是 CNI 插件没就绪。节点网络配置是 CNI 插件写出来的插件没装好kubelet 就会一直上报networkPluginNotReady。这个时候进节点查ls /etc/cni/net.d/如果这个目录是空的说明 CNI 插件没在 kubelet 发起调用前生成配置重新检查 Flannel 或 Calico 的 DaemonSet。第三是容器运行时本身异常。ctr version连不上 containerd 就没法用了。6.2 kubeadm init 失败后如何清理重来初始化失败最忌讳带着残留状态重跑不清理干净大概率还是失败而且报错也更难读。我的清理清单如下kubeadm reset -f rm -rf /etc/kubernetes /var/lib/kubelet /var/lib/etcd rm -rf /etc/cni/net.d iptables -F iptables -t nat -F iptables -t mangle -F iptables -X ipvsadm --clear # 如果用了 ipvs 模式kubeadm reset会自动清理 kubelet 相关配置但/etc/kubernetes和/var/lib/etcd这些目录不一定删得干净必须手动清理。iptables 规则如果不重置集群重建后新旧规则叠加网络行为会非常诡异我确实被这种问题坑过很久。清理完再重新走 init 流程基本都能顺利通过。6.3 证书过期与续期Kubernetes 证书默认有效期是一年实验环境跑得久一点就会遇到所有组件突然全线失效。遇到x509: certificate has expired or is not yet valid不用慌先看证书期限kubeadm certs check-expiration单 Master 场景最直接的方式是kubeadm certs renew all systemctl restart kubelet这里有个细节renew all只会续期证书并把新证书写到对应位置但 apiserver 等组件都是静态 Pod需要重启 kubelet 让它们以新的证书重新拉起来。操作顺序不能反。CPU、内存占用偏高的排查思路在单 Master 集群里格外重要。因为所有核心组件挤在一台机器上etcd、apiserver、kubelet 同时跑如果机器配置只有 2C4G压力大会出现 apiserver 响应慢、etcd 同步滞后等连锁反应。建议单 Master 实验集群至少给到 4C8G不要让业务负载太猛。真要跑较大的压力测试还是老老实实上多节点生产配置。7. 最终可用性验证与加固建议7.1 端到端验证六步法集群搭好不等于“能用”我一般按固定流程做最终验收确保核心链路无死角。第一步节点状态检查kubectl get nodes -o wide所有节点STATUS必须为Ready。第二步核心组件检查kubectl get pods -n kube-system所有系统组件READY列为1/1。第三步DNS 功能验证。前面用 busybox 测试过这里再确认一次coredns的 Pod IP 能响应解析。第四步创建测试 Deploymentkubectl create deployment echo-pod --imagebusybox -- sleep 3600第五步验证 Service 暴露和代理转发。把 Deployment 暴露成 NodePort从外部节点访问NodeIP:NodePort能通才说明 kube-proxy 工作正常。第六步验证节点故障感知。将某节点上的 Pod 删掉观察它是否在其他节点被重新调度。虽然单 Master 集群没有集群级高可用但工作节点上的业务 Pod 是有自愈能力的。7.2 安全与运维建议集群能用只算第一步后续运维才真正决定这集群能稳定跑多久。证书管理要按月检查推荐写个定时任务每两周输出一次kubeadm certs check-expiration的结果通知到期时间。etcd 备份这件事单 Master 也要做。执行etcdctl --endpoints127.0.0.1:2379 snapshot save /backup/etcd-snapshot.dbetcd 数据是集群唯一真源丢了它kubectl 里所有配置、状态全部清空。没有备份的集群和有备份的集群故障恢复时间差一轮数量级。最后说一句单 Master 集群的边界要心里有数。控制面节点挂了整个集群的管理面就瘫了已有的业务 Pod 虽然还在跑但无法调度、无法伸缩、无法更新。所以这类集群不要承载核心生产业务更适合作为预发验证、功能测试、技术培训的场景。等真正跑熟了这一套部署流程再往多控制面或托管集群迁移基本上就是在现有知识上做增量不会有太多学习成本。我个人踩过最多坑的还是网络插件和 cgroup 驱动这两个点每次换环境第一件事就是确认SystemdCgroup和 Pod 网段的一致性。把这一拍想明白了后面就是机械操作基本不会翻车。