搭 Kubernetes 集群这事儿很多人一上来就想着去搞二进制部署、自己签证书结果折腾两三天还没跑起来一个kubectl get nodes。其实在 CentOS 7 上用 kubeadm 走一遍标准流程才是最稳的路径尤其对于学习、测试、或者中小规模的生产环境来说kubeadm 能帮你把证书、组件配置、健康检查这些容易出错的部分自动化处理掉省下来的时间足够你去多排查几遍网络和存储的问题。这篇文章我会按自己实际在 CentOS 7 上反复搭过多次集群的经验把完整的搭建过程、每个步骤背后的原因、以及那些文档里不会写但实际一定会碰到的坑全部拆开讲清楚。不管你是第一次接触 Kubernetes还是之前搭过但总在某个环节卡住这篇内容应该能帮你少走不少弯路。1. 搭建前先想清楚的几件事版本选型与节点规划1.1 为什么在 CentOS 7 上用 kubeadm 而不是二进制部署CentOS 7 虽然已经进入了维护周期的后期但在很多公司的服务器机房里它依然是存量最大的操作系统。内核版本停留在 3.10很多新特性用不了但这并不妨碍它跑 Kubernetes关键是选对安装方式和版本组合。kubeadm 是 Kubernetes 官方提供的集群引导工具它的核心价值在于把 Etcd、API Server、Controller Manager、Scheduler 这些控制面组件以静态 Pod 的方式托管给 kubelet 去管理。你不需要自己手动去生成 CA 证书、配置每个组件的启动参数、做高可用 VIPkubeadm 会在初始化的时候把所有配置文件和证书都生成好放到/etc/kubernetes目录下。这就相当于你请了一个懂行的师傅帮你把最难的部分先干完了剩下的就是你自己去理解它生成的这些配置是什么意思。二进制部署虽然看起来更“透明”但你需要自己处理的东西太多了证书签发与轮换、组件之间的 TLS 通信配置、静态 Pod 的清单文件维护、升级策略……这些在没有充分经验的前提下很容易出错而且出了问题排查起来非常困难。我见过太多人在这个环节劝退最后又回来老老实实用 kubeadm。1.2 节点规划与硬件配置的实际参考规划节点前先明确一个原则Kubernetes 控制面组件API Server、Etcd、Scheduler、Controller Manager对资源的要求是刚性的尤其是 Etcd磁盘 IO 和内存都会直接影响整个集群的稳定性。基于 kubeadm 的默认部署方式我建议的最小规划如下角色数量最低配置建议配置Control PlaneMaster12C4G30G 磁盘4C8G50G SSDWorkerNode12C4G30G 磁盘4C8G100G SSD如果你只有一台机器又想体验完整功能可以在同一台机器上同时跑 Master 和 Worker也就是所谓的单节点集群。但在用 kubeadm 初始化的时候需要去掉默认的 Taint否则 Pod 不会被调度到 Master 节点上。这里特别提醒一下生产环境千万别这么干Etcd 和业务 Pod 抢资源会带来很多莫名其妙的问题。磁盘方面Etcd 对延迟非常敏感机械盘通常只适合测试环境我踩过几次坑之后发现哪怕硬盘老一点也尽量用 SSDEtcd 的写性能和磁盘 IO 直接挂钩机械盘跑久了会出现频繁的 leader election表现就是 API Server 时不时需要重新连接 Etcd。2. 主机初始化配置这些步骤漏掉一个都会坑你半天2.1 系统基础配置关闭 Swap、SELinux 与防火墙CentOS 7 拿到手之后不要急着装东西先把系统层的基础配置处理好。这一步做不好后面 kubeadm init 大概率会直接报错而且错误信息还特别不直观。第一件事关闭 Swap。Kubernetes 从设计上就假设节点上的 Pod 不会被交换到磁盘上因为一旦内存被 swap 拖慢整个节点的稳定性就无法保障。官方推荐的做法是在 kubelet 启动参数里加上--fail-swap-onfalse但在 CentOS 7 上用 kubeadm 的话直接在/etc/sysconfig/kubelet里配置这个参数是最省事的。当然如果你只是测试环境又不想改 kubelet 参数也可以直接swapoff -a并且注释掉/etc/fstab里的 swap 行二选一即可。第二件事SELinux 需要修改为 permissive 模式。注意是 permissive不是直接 disabled因为后续如果你要用一些依赖 SELinux 策略的存储插件permissive 模式下还能救一救直接 disabled 反而是最没弹性的做法。用 sed 命令替换掉配置文件里的SELINUXenforcing改成SELINUXpermissive然后重启或者setenforce 0临时生效。第三件事防火墙。CentOS 7 自带的 firewalld 在和 Kubernetes Service、NodePort 的联动上经常出问题因为 kube-proxy 用的是 iptables 模式而 firewalld 也管理 iptables 规则两者同时工作容易互相覆盖规则造成网络不通。最省心的做法就是systemctl stop firewalld systemctl disable firewalld测试环境和内网环境都推荐直接关掉。如果你的网络策略必须要开防火墙那得把 kube-apiserver 的 6443 端口、Etcd 的 2379/2380 端口、以及 NodePort 端口段全部放行并且要清楚知道这样配置的风险。2.2 内核参数与模块加载让网络转发和 IPVS 正常工作Kubernetes 集群内部的网络通信依赖 Linux 内核的桥接和转发能力CentOS 7 默认内核参数有几个地方需要调整。核心的参数是net.bridge.bridge-nf-call-iptables和net.bridge.bridge-nf-call-ip6tables这两个参数决定了经过 Linux 网桥的流量是否会被 iptables 规则处理。如果不开启即使你数据包转发开了跨 Pod 的通信也可能因为 iptables 规则没生效而失败。我把需要追加到/etc/sysctl.d/k8s.conf的内容整理一下cat EOF /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-ip6tables 1 net.bridge.bridge-nf-call-iptables 1 net.ipv4.ip_forward 1 vm.swappiness 0 EOF sysctl --system额外说明一下vm.swappiness 0这个参数是控制内存回收时使用 swap 的积极程度。虽然我们已经关掉了 swap但保留这个参数没坏处万一哪天你临时开了 swap系统也不会立刻把内存里的东西换出去。还有一个很容易被忽略的是 br_netfilter 模块。如果不先加载这个模块上面那几个 sysctl 参数配置后会出现cannot stat /proc/sys/net/bridge/bridge-nf-call-iptables: No such file or directory的报错。解决办法也很简单modprobe br_netfilter echo br_netfilter /etc/modules-load.d/br_netfilter.conf如果你打算用 IPVS 模式做 Service 负载均衡还要确认ip_vs相关内核模块被加载了检查方式lsmod | grep ip_vs在 CentOS 7 上一般自带这些模块没有的话装一下ipvsadm也能顺带加载。不过 kube-proxy 默认是 iptables 模式不想深入研究就先保持默认后面再切换也不迟。3. 容器运行时与 kubeadm 组件安装3.1 ContainerD 的安装与配置为什么在 CentOS 7 上选 containerdKubernetes 从 1.24 版本开始移除了对 Docker 的直接支持但这并不是说你不能在 Kubernetes 里用 Docker 镜像。只是 kubelet 不再直接跟 Docker 通信了而是通过 Container Runtime InterfaceCRI来跟容器运行时打交道。Docker 本身不实现 CRI所以中间需要 dockershim这个桥接层在 1.24 之后被删除社区推荐的替代方案就是 containerd。在 CentOS 7 上安装 containerd最稳的渠道是 Docker 的 yum 源虽然名字里带 docker但 containerd 就是从这个源里装出来的。配置好 Docker 源之后yum install -y containerd.io装完先别急着启动把默认的配置文件生成出来containerd config default /etc/containerd/config.toml这一步很多人省略了直接启动默认配置也可以但你会发现在拉取镜像的时候经常超时因为 containerd 默认用的是https://registry-1.docker.io国内网络环境访问很不稳定。我们需要在配置里改动两个关键点。第一是SystemdCgroup在config.toml里搜索SystemdCgroup把false改成true。这个参数决定了 containerd 使用 cgroupfs 还是 systemd 作为 cgroup 驱动。在 CentOS 7 上kubelet 默认使用 systemd 作为 cgroup 驱动如果 containerd 这边还是 cgroupfs两者不一致kubelet 在检查节点状态的时候会报failed to validate cgroup节点直接变成 NotReady。第二是镜像加速。在config.toml里找到[plugins.io.containerd.grpc.v1.cri.registry]这段给它加上 mirrors 配置替换成国内可用的镜像仓库地址。这一步能让你后续所有拉取镜像的操作快很多。配置完成后重启 containerdsystemctl restart containerd systemctl enable containerd3.2 使用 kubeadm、kubelet、kubectl 安装与版本锁定这三个组件建议用 Kubernetes 官方的 yum 源来安装。CentOS 7 对应的官方源地址在https://mirrors.aliyun.com/kubernetes/yum/我把这个配置到/etc/yum.repos.d/kubernetes.repocat EOF /etc/yum.repos.d/kubernetes.repo [kubernetes] nameKubernetes baseurlhttps://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64 enabled1 gpgcheck0 repo_gpgcheck0 EOF这里把 gpgcheck 全部关掉了内网环境没有签名 key 也能直接装。如果你有洁癖想保留 gpgcheck那就得先导入官方的 GPG key不然 yum 会报错。安装的命令很简单但强烈建议指定版本号。CentOS 7 上如果你直接yum install -y kubeadm kubelet kubectl它会装到当前源里的最新版本而最新版本对 CentOS 7 的内核和系统库要求有时候并不友好。我自己搭集群一般选择 1.28 系列这个版本在 CentOS 7 上稳定功能也足够新。yum install -y kubelet-1.28.0 kubeadm-1.28.0 kubectl-1.28.0装完之后顺手systemctl enable kubelet注意这里只需要 enable不要 start因为 kubelet 要等 kubeadm init 生成了配置之后才能正常工作。3.3 提前拉取镜像这一步能省掉你 80% 的失败概率kubeadm init 在执行过程中会去拉取一系列控制面组件的镜像比如 kube-apiserver、kube-controller-manager、kube-scheduler、etcd、coredns 等。如果你直接跑kubeadm init它会按照默认配置去registry.k8s.io拉取镜像这个地址在国内基本处于不可用状态。所以在初始化之前一定要先干一件事用 kubeadm 预检一下需要什么镜像然后替换源拉取。kubeadm config images list执行结果会列出所有需要的镜像名称和版本。然后我们用 kubeadm 的--image-repository参数来指定一个国内可访问的仓库阿里云的镜像源比较稳定kubeadm config images pull --image-repositoryregistry.aliyuncs.com/google_containers执行完确认所有镜像都 pulls 成功Kubernetes 初始化真正的风险点就排除了。这里我遇到过一个容易忽略的问题registry.aliyuncs.com/google_containers里镜像的 tag 和官方registry.k8s.io不完全一致个别版本可能出现 pull 不到的情况。解决的办法是手动用docker tag或者ctr命令把对应的镜像重新打一个期望的 tag细节后续在排查环节再说。4. 集群初始化kubeadm init 全流程拆解4.1 初始化参数与 kubeadm 配置文件很多教程直接让你跑kubeadm init --pod-network-cidr10.244.0.0/16参数写一长串看起来简单但改起来不方便。我习惯先把配置写到一个 YAML 文件里这样后续想加参数、想改配置都只是编辑文件的事。先执行kubeadm config print init-defaults kubeadm-init.yaml然后编辑这个文件最核心的几个地方localAPIEndpoint.advertiseAddress改成 Master 节点的内网 IP这是 API Server 对外广播的地址如果写错了Node 节点 join 进来后会连不上 API Server。nodeRegistration.name改成 Master 节点的主机名注意如果系统 hosts 文件里没配好对应关系这里还是会有报错提前在/etc/hosts里加一行内网IP 主机名。imageRepository改成registry.aliyuncs.com/google_containers。podSubnet设置成10.244.0.0/16。这个网段要和后面装的网络插件保持一致否则 Pod 网段和 CNI 插件管理的网段对不上一创建 Pod 就 CrashLoopBackOff。4.2 执行初始化与输出结果解读配置就位后执行kubeadm init --config kubeadm-init.yaml这个过程正常情况下会持续两三分钟输出信息非常多但你需要关注几个关键位置末尾会打印出一个kubeadm join命令形如kubeadm join 192.168.x.x:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx。这个命令要复制保存好后面节点要加入集群就靠它。如果过期了也没关系可以用kubeadm token create --print-join-command再生成一条。提示配置 kubectl 的步骤kubeadm 默认不会帮你把kubelet的配置文件暴露给当前用户你需要手动创建.kube目录并复制 admin.conf。初始化完成后的验证export KUBECONFIG/etc/kubernetes/admin.conf kubectl get nodes此时 Master 节点的状态可能是NotReady这是正常的因为网络插件还没有部署。只有当你看到节点状态变为Ready整个初始化才算真正完成。4.3 工作节点加入集群token 管理与注意事项Worker 节点的加入过程本质上就是在 Worker 节点上执行一条 join 命令。但在 join 之前要有两个前置条件Worker 节点已经按照第 2 节的内容完成了主机初始化。Worker 节点已经按照第 3 节的内容安装好了 containerd 和 kubelet、kubeadm并且 containerd 的配置和 Master 节点保持一致。对于 Worker 节点无需执行 kubeadm init只需要执行kubeadm join 192.168.x.x:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx如果控制面节点的 kubeadm 网络地址配置正确join 过程很快。但如果这个过程失败多半是以下三种情况token 过期、证书 hash 不匹配、网络端口不通。查 token 是否依然有效在控制面节点执行kubeadm token list不行就重新生成一条新的 join 命令之前说的kubeadm token create --print-join-command就是干这个用的。端口不通的问题优先检查控制面节点的 6443 端口是否被防火墙挡住最简单的方法就是全部关闭防火墙。5. 网络插件部署Calico 的安装与验证5.1 CNI 插件的选型为什么推荐 CalicoKubernetes 集群建起来之后节点和 Pod 之间的网络还没有打通必须找一个 CNIContainer Network Interface插件来实现。常见的选项是 Flannel 和 Calico。Flannel 的优势在于简单安装容易网络模型是 VXLAN 或 host-gateway性能凑合。但它的短板也很明显不支持 Network Policy。如果你的集群规模还小只用 Flannel 完全没问题但我个人还是更推荐 Calico。Calico 的核心优势在于它用的不是隧道封装方案而是基于 BGP 的纯三层网络方案性能更好网络路径更短同时支持 Network Policy这意味着你可以在 Kubernetes 里用网络策略进行更细粒度的流量管控。BGP 的数据包是被 Linux 内核直接路由的不像 VXLAN 需要额外的封包解包开销在网络吞吐要求高的业务场景下差距尤其明显。5.2 部署 Calico 的完整步骤Calico 官方提供了 operator 方式的安装也可以直接用 manifest 文件一把梭。按我自己的习惯用 operator 更多一些但这里分享一个用 manifest 直接部署的方式步骤简单清晰适合快速落地。首先下载 Calico 的 manifest 文件注意版本要和 Kubernetes 对应。我用 1.28 的集群Calico 选 3.27 或更新的版本都可以curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml这个 manifest 会在集群里创建一堆资源对象包括 DaemonSet、CRD、RBAC 等。部署前要检查一下里面 ConfigMap 里的网段是否和你在 kubeadm init 里设置的podSubnet一致。默认配置用的就是10.244.0.0/16如果你的集群用的也是这个网段那基本不用改。执行部署kubectl apply -f calico.yaml部署之后等待 Pod 创建完成kubectl get pods -n calico-system看到所有calico-node的 Pod 都是 Running节点状态应该很快就变成 Ready 了。这里有一个我踩过的坑如果 Sistema 里 calico-node 报 BGP 无法建立对等体多半是 IP 自动检测出了问题Calico 默认会读取节点的网卡 IP如果你的服务器有多块网卡需要手动指定IP_AUTODETECTION_METHOD变量比如interfaceeth.*来限定网卡。5.3 网络就绪验证从 Pod 到 Service 的链路网络插件部署完之后需要验证集群的整个数据链路是否通畅。我最常用的验证方式是在集群里跑一个测试 Pod然后跨节点访问。先创建一个简单的 nginx 测试 Podkubectl create deployment test-nginx --imagenginx kubectl expose deployment test-nginx --port80 --target-port80 --typeNodePort然后查看 Service 的 NodePort 端口kubectl get svc test-nginx再用curl访问这个 NodePort如果通了说明节点上的 kube-proxy 规则、iptables 转发、Pod 内部的监听都正常。进一步验证跨节点通信kubectl run busybox --imagebusybox --rm -it -- sh进入 busybox 之后执行wget -O- http://test-nginx-pod-ip如果能访问到说明 Pod 到 Pod 之间的跨节点网络是通的。这一步通常能发现 Flannel 或 Calico 的 BGP 配置问题、以及ip_forward没开启的问题。6. 常见问题排查与避坑实录6.1 初始化失败的几种典型情况初始化失败是新手遇到最多的问题。总结下来主要是这几类端口被占用。比如 10250、10251、10252 这些 kubelet 和组件的默认端口已经被占用了kubeadm 会直接报错说端口被 bind。端口占用的排查方法很简单执行ss -lntp | grep -E 10250|10251|10252|6443找到占用的进程处理掉。测试环境我见过最多的是 10250 被其他服务占了比如你自己装的监控 agent 之类的。Docker 和 containerd 的 cgroup driver 不一致。这个问题在第 3 节说过报错信息里有一个很明显的特征failed to run Kubelet errfailed to run kubelet isDockerfalse。出现这行字直接去检查 containerd 的 config.toml 里SystemdCgroup是不是true。版本不一致。kubelet 和 kubeadm 的版本必须一致否则 init 起来虽然能跑但 kubelet 会起不来了。最好的习惯就是安装时直接把版本号锁死。6.2 节点状态 NotReady 的常见原因节点状态始终停留在NotReady这个问题在初始化网络插件前后最容易出现。分为两种情况讨论。如果网络插件还没部署的时候 Master 节点是 NotReady那是正常的。可一旦 Calico 部署完还是 NotReady那就得从头查了journalctl -u kubelet -f大部分人遇到的情况还是 kubelet 报错Failed to get system container stats、failed to get cgroup stats for container之类。这类信息会引导你回到 cgroup 驱动的问题上。另一种常见情况是 CNI 插件没有正常启动kubectl get pods -n kube-system看下coredns或calico-node是否 Running如果一直是 ContainerCreating 状态大概率是镜像拉取失败或者节点上的子网配置不对。6.3 Pod 长时间 Pending 或 CrashLoopBackOffPod 一直处于 Pending 状态通常有两个原因没有节点满足调度条件或者没有可用资源。这个最容易犯的错是资源预留不够比如测试环境节点只有 2C4G但你直接部署了一堆 Calico 组件剩余资源不足以调度业务 Pod。稳妥的观测手段kubectl describe pod pod-nameEvents 里会明确写清楚为什么 Pending比如Insufficient memory、0/1 nodes are available之类的。我之前遇到过一次很隐蔽的问题单节点集群明明资源充足但 Pod 就是一直 Pending查了半天发现是 Master 节点上有默认的 Taint没有加 toleration 的 Pod 无法调度上去。找到问题之后在部署时加上对应的 toleration或直接去掉这个 Taintkubectl taint nodes --all node-role.kubernetes.io/control-plane-CrashLoopBackOff 最常见于镜像启动失败比如镜像的 entrypoint 有问题、配置文件路径不对、容器内外端口不匹配。CoreDNS 的 CrashLoopBackOff 很典型多半是coredns镜像拉不到或者 Liveness 探针配置有问题看我后面给你的排查思路就够了先kubectl logs看容器输出内容再kubectl describe pod看探针是否失败然后结合资源限制去看。6.4 镜像拉取永远的痛手动打 tag 的解决方案如果你遇到某些镜像在registry.aliyuncs.com/google_containers里拉取不到或者 tag 不匹配不要硬扛手动打 tag 是最快的方案。比如你需要registry.k8s.io/pause:3.9这个镜像但实际上拉到了registry.aliyuncs.com/google_containers/pause:3.6解决办法ctr -n k8s.io images tag registry.aliyuncs.com/google_containers/pause:3.6 registry.k8s.io/pause:3.9注意ctr是 containerd 自带的 CLI如果你用的还是 Docker 运行时用docker tag也是一样。这个操作本质就是本地改一个引用关系不影响上游镜像的任何内容。6.5 重启后集群起不来的处理思路服务器重启后Kubernetes 集群没有自动恢复这个问题也经常被问到。起因大多数是 containerd 和 kubelet 服务没有设置开机自启或者 etcd 数据损坏这个一般跟非正常关机有关。正确做法是提前就把服务全部 enablesystemctl enable containerd kubelet如果已经重启挂了按顺序启动先启动 containerd再启动 kubelet然后检查kubectl get nodes。如果节点状态还不是 Ready就得去看 kubelet 日志journalctl -u kubelet -n 1006.6 常见问题速查表现象根因解决方案init 报错端口占用其他进程占用 kubelet 端口查端口占用进程并释放kubelet 无法启动cgroup 驱动不一致修改 containerd 配置 SystemdCgroup 为 true节点 NotReady网络插件未部署或异常检查 Calico Pod 状态确认网段一致Pod Pending资源不足或 Taint 未容忍检查节点资源、Taint 规则镜像拉取超时registry 网络不通配置镜像加速或手动改 tagCoreDNS CrashLoopBackOff镜像或探针问题kubectl logs describe 定位7. 集群搭建完成后的基础操作与验证建议集群搭好只是万里长征第一步后面还有业务部署、日志收集、监控告警一堆事情要做。但有几个检查项我建议你搭完集群后就立刻执行能提前发现很多潜在问题。先验证集群组件是否健康kubectl get cs kubectl get pods -n kube-system kubectl get nodes接着创建几个简单的工作负载跑一下 Service 的 ClusterIP 访问再试一下 NodePort 对外暴露看看 kube-proxy 的 iptables 规则是否正常。如果你打算跑有状态应用那存储相关的 StorageClass 也要尽早规划起来CentOS 7 上用 NFS 做动态供给是很常见的做法。另外kubeadm 生成的证书默认有效期是一年到期之后kubectl会报证书过期。这是一个很容易被忽视的点建议在集群搭建完就配一个定时任务提醒自己或者用 cron 定时执行kubeadm certs renew all个人经验总结CentOS 7 上搭 Kubernetes 这件事难的不是执行 kubeadm init 的那几分钟而是前面那些系统层面的准备工作和后面网络插件的调试。我见过太多人在 Step 2 系统配置那里栽跟头或者在 Step 5 网络插件那里反复重启节点。把文章里这些细节都检查一遍集群大概率能一次起来。最后再分享一个小技巧建议每完成一个阶段就拍个快照或者至少把/etc/kubernetes、/etc/containerd/config.toml、kubeadm-init.yaml这几个关键文件备份好。集群出问题的时候回滚和排查的速度会快很多。