CentOS 7实战：kubeadm搭建Kubernetes集群完整指南

搭 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 证书、配置每个组件的启动参数、做高可用 VIP，kubeadm 会在初始化的时候把所有配置文件和证书都生成好，放到/etc/kubernetes目录下。这就相当于你请了一个懂行的师傅帮你把最难的部分先干完了，剩下的就是你自己去理解它生成的这些配置是什么意思。

二进制部署虽然看起来更“透明”，但你需要自己处理的东西太多了：证书签发与轮换、组件之间的 TLS 通信配置、静态 Pod 的清单文件维护、升级策略……这些在没有充分经验的前提下很容易出错，而且出了问题排查起来非常困难。我见过太多人在这个环节劝退，最后又回来老老实实用 kubeadm。

1.2 节点规划与硬件配置的实际参考

规划节点前先明确一个原则：Kubernetes 控制面组件（API Server、Etcd、Scheduler、Controller Manager）对资源的要求是刚性的，尤其是 Etcd，磁盘 IO 和内存都会直接影响整个集群的稳定性。

基于 kubeadm 的默认部署方式，我建议的最小规划如下：

如果你只有一台机器，又想体验完整功能，可以在同一台机器上同时跑 Master 和 Worker，也就是所谓的单节点集群。但在用 kubeadm 初始化的时候需要去掉默认的 Taint，否则 Pod 不会被调度到 Master 节点上。这里特别提醒一下，生产环境千万别这么干，Etcd 和业务 Pod 抢资源会带来很多莫名其妙的问题。

磁盘方面，Etcd 对延迟非常敏感，机械盘通常只适合测试环境，我踩过几次坑之后发现，哪怕硬盘老一点也尽量用 SSD，Etcd 的写性能和磁盘 IO 直接挂钩，机械盘跑久了会出现频繁的 leader election，表现就是 API Server 时不时需要重新连接 Etcd。

2. 主机初始化配置：这些步骤漏掉一个都会坑你半天

2.1 系统基础配置：关闭 Swap、SELinux 与防火墙

CentOS 7 拿到手之后，不要急着装东西，先把系统层的基础配置处理好。这一步做不好，后面 kubeadm init 大概率会直接报错，而且错误信息还特别不直观。

第一件事，关闭 Swap。Kubernetes 从设计上就假设节点上的 Pod 不会被交换到磁盘上，因为一旦内存被 swap 拖慢，整个节点的稳定性就无法保障。官方推荐的做法是在 kubelet 启动参数里加上--fail-swap-on=false，但在 CentOS 7 上用 kubeadm 的话，直接在/etc/sysconfig/kubelet里配置这个参数是最省事的。当然，如果你只是测试环境，又不想改 kubelet 参数，也可以直接swapoff -a并且注释掉/etc/fstab里的 swap 行，二选一即可。

第二件事，SELinux 需要修改为 permissive 模式。注意是 permissive，不是直接 disabled，因为后续如果你要用一些依赖 SELinux 策略的存储插件，permissive 模式下还能救一救，直接 disabled 反而是最没弹性的做法。用 sed 命令替换掉配置文件里的SELINUX=enforcing，改成SELINUX=permissive，然后重启或者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 上选 containerd

Kubernetes 从 1.24 版本开始移除了对 Docker 的直接支持，但这并不是说你不能在 Kubernetes 里用 Docker 镜像。只是 kubelet 不再直接跟 Docker 通信了，而是通过 Container Runtime Interface（CRI）来跟容器运行时打交道。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 配置，替换成国内可用的镜像仓库地址。这一步能让你后续所有拉取镜像的操作快很多。

配置完成后，重启 containerd：

systemctl restart containerd systemctl enable containerd

3.2 使用 kubeadm、kubelet、kubectl 安装与版本锁定

这三个组件建议用 Kubernetes 官方的 yum 源来安装。CentOS 7 对应的官方源地址在https://mirrors.aliyun.com/kubernetes/yum/，我把这个配置到/etc/yum.repos.d/kubernetes.repo：

cat <<EOF > /etc/yum.repos.d/kubernetes.repo [kubernetes] name=Kubernetes baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64 enabled=1 gpgcheck=0 repo_gpgcheck=0 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-repository=registry.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-cidr=10.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 插件的选型：为什么推荐 Calico

Kubernetes 集群建起来之后，节点和 Pod 之间的网络还没有打通，必须找一个 CNI（Container 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变量，比如interface=eth.*来限定网卡。

5.3 网络就绪验证：从 Pod 到 Service 的链路

网络插件部署完之后，需要验证集群的整个数据链路是否通畅。我最常用的验证方式是在集群里跑一个测试 Pod，然后跨节点访问。

先创建一个简单的 nginx 测试 Pod：

kubectl create deployment test-nginx --image=nginx kubectl expose deployment test-nginx --port=80 --target-port=80 --type=NodePort

然后查看 Service 的 NodePort 端口：

kubectl get svc test-nginx

再用curl访问这个 NodePort，如果通了，说明节点上的 kube-proxy 规则、iptables 转发、Pod 内部的监听都正常。

进一步验证跨节点通信：

kubectl run busybox --image=busybox --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" err="failed to run kubelet" isDocker==false。出现这行字，直接去检查 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 或 CrashLoopBackOff

Pod 一直处于 Pending 状态，通常有两个原因：没有节点满足调度条件，或者没有可用资源。这个最容易犯的错是资源预留不够，比如测试环境节点只有 2C4G，但你直接部署了一堆 Calico 组件，剩余资源不足以调度业务 Pod。稳妥的观测手段：

kubectl describe pod <pod-name>

Events 里会明确写清楚为什么 Pending，比如Insufficient memory、0/1 nodes are available之类的。我之前遇到过一次很隐蔽的问题：单节点集群，明明资源充足，但 Pod 就是一直 Pending，查了半天发现是 Master 节点上有默认的 Taint，没有加 toleration 的 Pod 无法调度上去。找到问题之后在部署时加上对应的 toleration，或直接去掉这个 Taint：

kubectl 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 数据损坏（这个一般跟非正常关机有关）。正确做法是提前就把服务全部 enable：

systemctl enable containerd kubelet

如果已经重启挂了，按顺序启动：先启动 containerd，再启动 kubelet，然后检查kubectl get nodes。如果节点状态还不是 Ready，就得去看 kubelet 日志：

journalctl -u kubelet -n 100

6.6 常见问题速查表

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这几个关键文件备份好。集群出问题的时候，回滚和排查的速度会快很多。