kubeadm实战：从零搭建Kubernetes单Master多Node集群

第一次手工部署 k8s 时，我只用一天就意识到，如果每个节点都靠手动 copy 二进制、自签证书、维护 systemd 服务，这套系统注定只能停留在测试环境。kubeadm 是目前把“单 master 多 node”集群搭建成本压到最低的工具，它把证书生成、组件静态 Pod 编排、kubeconfig 下发、token 引导这一整套流程封装成了可复现的命令。这篇作为系列第一篇，目标就一个：带你把一套能正常跑业务、能扩容 worker 节点的集群搭起来，同时把每个步骤背后的原因讲透。适合对容器有基本了解、还没有完整搭建过集群的同学，也适合搭完一次但踩过不少坑想回头补概念的人。

1. 动手前先把架构盘明白：kubeadm、master、node 各管一摊

1.1 单 master 集群的部件构成

kubeadm 搭出来的集群，本质上还是那套标准 Kubernetes 控制面组件，只不过它把这些组件从二进制进程变成了容器形态去托管。一个单 master 多 node 集群里，职责分两层：

• 控制平面（master）：跑着 kube-apiserver、kube-controller-manager、kube-scheduler，以及 etcd 存储。所有对集群的读写请求都要经过 apiserver，它是整个集群的“调度总机”。
• 工作节点（node）：跑着 kubelet、kube-proxy 和容器运行时。kubelet 负责跟 apiserver 通信、接收 Pod 调度请求、监控本机容器状态；kube-proxy 负责维护节点的网络规则，让 Service 能转发流量。

kubeadm 做的事情，就是把这些组件的配置文件、证书、静态 Pod 清单全部生成好，再交给 kubelet 以静态 Pod 方式启动。也就是说，你不需要手工装 etcd、手工签 CA 证书，只要 init 一下，控制面自己就起来了。

1.2 为什么选 kubeadm 而不是二进制和 minikube

很多新手会问：我直接下二进制手动部署行不行？行，但对入门阶段的人来说成本极高。二进制方式需要自己处理 CA 证书、kubeconfig、etcd 集群、组件启动顺序，任何一个环节错了都要看日志追半天。kubeadm 的好处是：

• 流程标准化：一条 init 命令完成控制面初始化，一条 join 命令让节点加入，证书和 token 机制都内置。
• 升级可控：kubeadm upgrade 可以按版本逐级升级控制面组件，比手改配置稳得多。
• 可审计、可回滚：init 生成的配置在 /etc/kubernetes 下，关键动作都有清晰输出。

minikube 适合单机学习，但它只有一个节点，没办法体会多节点调度、Pod 漂移、节点 NotReady 这类真实运维场景。生产环境里大量线上集群也是 kubeadm 或者基于 kubeadm 思路的部署工具（比如 RKE、Kubespray）搭出来的，所以从这个工具入门，后续要往生产方向走也不吃亏。

1.3 k8s 和 docker 经常被放在一起问，到底什么关系

搜索里经常出现“k8s 和 docker 区别”，这里花一点篇幅说清楚：Docker 是容器运行时，负责把镜像变成运行中的容器；Kubernetes 是容器编排平台，负责决定这些容器跑在哪台机器、挂了怎么拉起、流量怎么负载均衡。两者不是二选一的关系，而是一个管单机、一个管集群。

具体到新版 kubeadm 集群，默认使用的容器运行时已经不是 Docker Engine，而是 containerd。因为 containerd 更轻，也原生兼容 CRI（Container Runtime Interface）。即便你安装镜像是用 docker build 打出来的，只要符合 OCI 标准，containerd 就能直接跑。实际搭建中，你只需要保证容器运行时正常工作，不用纠结 k8s 是不是需要用 docker 命令来管理容器。

2. 规划阶段决定后面的成功率：版本、资源、网段三件事

2.1 版本选择和组件一致性

kubeadm、kubelet、kubectl 这三个二进制最好装同一个版本，控制平面版本和节点 kubelet 版本也不能相差超过一个小版本。我自己遇到过 kubelet 比 apiserver 新两个小版本导致节点反复 NotReady 的情况，日志看着像证书问题，其实根源就是版本不对称。

建议用当前稳定版本，比如 v1.30.x 或 v1.31.x，具体以你操作时的官方 release 为准。小版本号不必刻意追最新，选一个已经迭代过几个 patch 的版本更稳妥。有个细节：kubeadm init 默认会拉取最新稳定版，但如果你的网络环境对特定版本拉取失败，可以显式指定 --kubernetes-version=v1.30.0 这样的参数，避免版本变化带来干扰。

2.2 资源底线

单 master 多 node 集群虽然比单机复杂，但对资源要求并没有想象中高。我这边实测的最低配置参考：

注意这里说的是“能跑起来”的最低配置，如果你还要部署数据库、日志采集、监控这些组件，内存建议翻倍。etcd 对磁盘 IO 敏感，机械盘在频繁写入时容易造成 apiserver 请求变慢，有条件的话 master 用 SSD。

2.3 网络规划：Pod 网段、Service 网段、节点 IP 怎么分配

Kubernetes 集群有三层网络叠加，很多人没提前规划，后面装好 CNI 才发现地址冲突。

• 节点网络：就是服务器之间的真实 IP，比如 192.168.1.10、192.168.1.11。
• Pod 网络：给每个 Pod 分配的内部 IP，CIDR 一般取 10.244.0.0/16 或 10.96.0.0/12，这个网段必须跟现有网络不冲突。
• Service 网络：给 Service 虚拟 IP 用的，默认是 10.96.0.0/12。

如果你选了 Flannel，它默认就要用 10.244.0.0/16 这个段，所以 kubeadm init 时 --pod-network-cidr=10.244.0.0/16 要和插件的默认配置对齐。如果选了 Calico，默认是 192.168.0.0/16，需要改配置或者让 init 参数和它匹配。说白了，pod 网段不是随便填的，你必须先想好用哪个 CNI，再回来定这个参数。

3. 基础环境三步走：每一台机器都逃不掉

3.1 系统初始化：主机名、解析、防火墙、swap

这一节开始在 master 和所有 node 上逐台操作。先用 SSH 登录，把主机名改成有辨识度的名字，比如 master01、node01、node02。主机名不能重复，而且建议不要带大写字母和下划线，Kubernetes 组件对主机名的要求比较严格。

bash复制hostnamectl set-hostname master01
hostnamectl set-hostname node01

然后编辑 /etc/hosts，把集群内所有节点的 IP 和主机名写进去，这样即使内网 DNS 不完善，kubelet 和 kubeadm join 时也能正确定位其他节点。

bash复制192.168.1.10 master01
192.168.1.11 node01
192.168.1.12 node02

防火墙是第一个坑。如果机器上有 firewalld，可以先把 6443、2379-2380、10250、30000-32767 这些端口放通，或者在测试环境里直接关闭防火墙。生产环境不要关防火墙，用规则精确放行。SELinux 同理，RHEL/CentOS/Rocky 上如果没配置好，kubelet 很容易读不到 Pod 文件，建议先 setenforce 0，等集群跑起来再研究怎么样在开 SELinux 的情况下正常工作。

swap 必须关。kubelet 默认不允许节点开启 swap，否则会报 “running with swap on is not supported”。执行：

bash复制swapoff -a
sed -i '/ swap / s/^/#/' /etc/fstab

这里 sed 是把 /etc/fstab 里的 swap 行注释掉，保证重启后不会又自动挂载。只执行 swapoff 不处理 fstab，重启后照样翻车。

再加载几个内核模块：

bash复制modprobe overlay
modprobe br_netfilter
echo -e "overlay\nbr_netfilter" > /etc/modules-load.d/k8s.conf
cat <<EOF > /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
sysctl --system

br_netfilter 负责让 iptables 规则能作用于网桥流量，如果没加载，kube-proxy 的转发规则可能不会生效。

3.2 容器运行时就位：containerd 与 cgroup 驱动

kubeadm 集群里，kubelet 直接通过 CRI 和 containerd 通信。以 Ubuntu 22.04 为例，先安装依赖：

bash复制apt-get update && apt-get install -y ca-certificates curl gnupg

添加 Docker 官方仓库不是用来装 Docker Engine，而是为了拿 containerd.io 包。如果系统里已经装了 docker-ce，自带的 containerd 也能用，但要注意版本别太老。

bash复制install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
apt-get update && apt-get install -y containerd.io

装完之后必须做 cgroup 驱动对齐。kubelet 默认用 systemd 作为 cgroup driver，containerd 默认配置可能是 cgroupfs，两者不一致会导致节点起不来。解决办法是生成默认配置再改一个字段：

bash复制containerd config default | sudo tee /etc/containerd/config.toml

打开 /etc/containerd/config.toml，找到 SystemdCgroup，把它改成 true。这一步是新手最容易忽略的地方。改完重启：

bash复制systemctl restart containerd
systemctl enable containerd
systemctl status containerd

3.3 安装 kubeadm、kubelet、kubectl 并锁定版本

Kubernetes 官方给出了 apt 仓库安装方式，这里直接列命令。先加 key 和源：

bash复制curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/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.30/deb/ /" > /etc/apt/sources.list.d/kubernetes.list
apt-get update

查看可用版本：

bash复制apt-cache madison kubeadm

然后安装指定版本：

bash复制apt-get install -y kubelet=1.30.4-1.1 kubeadm=1.30.4-1.1 kubectl=1.30.4-1.1

装完立刻执行 apt-mark hold：

bash复制apt-mark hold kubelet kubeadm kubectl

这一步非常关键。如果不锁定版本，一次 apt-get upgrade 就可能把 kubelet 升上去，结果和集群里其他组件版本不匹配，整个集群可能完蛋。RHEL/CentOS/Rocky 系用 yum install 加版本号，再用 yum versionlock 实现同样的效果。

装完先别急着 init，执行一下 kubeadm version 和 kubelet --version，确认三个命令的版本号一致再继续。

4. 主节点初始化：kubeadm init 的参数不是随便写的

4.1 初始化前先做镜像准备

kubeadm init 会先做检查，然后从镜像仓库拉取控制面组件镜像。这一步非常耗时，也最容易因为网络问题卡住。建议先用这个命令提前把镜像列表打出来：

bash复制kubeadm config images list

mysql格式看清楚了，它列出来的是 etcd、pause、kube-apiserver、kube-controller-manager、kube-scheduler 这些镜像。可以在 init 之前先执行 kubeadm config images pull，把所有镜像拉下来。如果这一步因为网络不稳定导致失败，先确认 DNS、代理、仓库可达性，等镜像全部 pull 成功再 init，能省掉很多中途失败的麻烦。

4.2 初始化参数逐项拆解

在 master01 上执行，下面这组命令我实测比较稳定：

bash复制sudo kubeadm init \
  --apiserver-advertise-address=192.168.1.10 \
  --control-plane-endpoint=192.168.1.10 \
  --pod-network-cidr=10.244.0.0/16 \
  --kubernetes-version=v1.30.4 \
  --cri-socket=unix:///var/run/containerd/containerd.sock

参数含义有必要展开说：

• --apiserver-advertise-address：apiserver 对外通告的 IP。单 master 场景直接填 master 节点的内网 IP。如果填错，之后 kubectl get nodes 会看到连接被拒绝。
• --control-plane-endpoint：控制面统一入口，单 master 就填 master IP。生产环境做高可用时要填负载均衡 VIP，所以这个参数建议从一开始就养成填写的习惯。
• --pod-network-cidr：前面规划好的 Pod 网段，这里选了 10.244.0.0/16 是为 Flannel 默认值对齐。
• --kubernetes-version：指定版本，避免 kubeadm 自己猜一个和 repo 不同的版本。
• --cri-socket：明确指定 containerd 的 socket 路径，防止环境里有多个容器运行时导致探测错误。

等初始化跑完，最后几行会给出两种后续操作的提示：一种是 kubectl 配置方法，一种是 worker 节点 join 命令。建议把 join 命令完整复制到一个文本文件里保存，后面会用到。

如果初始化失败，先看输出里的 error 提示，常见的是端口被占用、镜像拉取失败、swap 没关。一条一条排除后，可以执行 kubeadm reset 清掉残留配置再重来。

4.3 配置 kubectl

初始化成功之后，普通用户还不能直接运行 kubectl，因为管理员的 kubeconfig 文件在 /etc/kubernetes/admin.conf，需要复制到个人目录：

bash复制mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

配置文件里包含了 CA 证书、客户端证书和 apiserver 地址，是连接集群的钥匙。之后运行：

bash复制kubectl get nodes

应该能看到 master01 状态是 NotReady。这个是正常的，因为网络插件还没装，节点状态会在组件的 readiness 检查通过后自动变 Ready。

4.4 CNI 网络插件必须做，选 Flannel 还是 Calico

没有 CNI（Container Network Interface）插件，集群里 Pod 之间是没法通信的，coredns 也无法启动，所以这一步不能省。选型上给个实用建议：

• Flannel：简单、够用，适合集群内流量不大、不需要复杂网络策略的学习环境。安装命令：

bash复制kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

如果拉取这个 yaml 文件有问题，先解决网络可达性，或者下载后 apply 本地文件。Flannel 默认使用 VXLAN 模式，性能中规中矩，但胜在逻辑清晰，排障容易。

• Calico：功能更强，支持 NetworkPolicy、BGP 路由，生产环境用得多。安装方式：

bash复制kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27/manifests/calico.yaml

Calico 的默认 Pod 网段是 192.168.0.0/16，如果你的 init 参数里写的是 10.244.0.0/16，就得把 calico.yaml 里的 192.168.0.0/16 改成 10.244.0.0/16 再 apply。

新手最容易犯的错是 Flannel 和 Calico 各 apply 一遍，结果两个插件抢着修网络，节点反复 CrashLoopBackOff。一旦上了其中一个，就不要再装另一个，排查问题时先 kubectl get pods -n kube-flannel 或 kubectl get pods -n calico-system 看插件状态。

装完插件后等 1 到 2 分钟，再执行 kubectl get pod -A，应该能看到 coredns 都处于 Running 状态。

5. 多 Node 扩容：一条 join 命令背后涉及的机制

5.1 token 机制：为什么需要且会过期

node 节点加入集群，核心动作是向 kube-apiserver 发起 join 请求，但 apiserver 不可能无脑放行所有机器，所以 kubeadm 用了两层校验：token 和 CA 证书 hash。token 相当于临时门票，CA 证书 hash 用来确认你连的确实是这个集群的 apiserver。

从 init 输出里复制到的 join 命令长这样：

bash复制sudo kubeadm join 192.168.1.10:6443 --token abcdef.0123456789abcdef \
    --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

token 默认有效期 24 小时，过期之后再用就报 “token is already expired”。这时候不用重装集群，在 master 上重新生成一条 join 命令：

bash复制kubeadm token create --print-join-command

这个命令会把新 token 和当前 CA 证书的 hash 一起打印出来，复制到 node 上执行即可。

5.2 worker 节点上的验证

在 node01、node02 上先把第 3 节的基础环境全部做完，确保 kubelet、kubeadm、containerd 都在运行，然后在 node 上执行 join 命令。执行成功后，node 的姿态是“等待 apiserver 承认”，回到 master 上：

bash复制kubectl get nodes

大概几十秒后能看到 node01、node02 出现在列表里，状态从 NotReady 变成 Ready。如果一直卡在 NotReady，优先看 kubelet 日志：

bash复制journalctl -u kubelet -f

日志里常见的原因包括：网络插件没装好、容器运行时 socket 配置不对、cgroup driver 不一致。看到具体关键字再对症处理，不要一上来就 reset。

5.3 节点角色标注与后续扩容

默认情况下，join 进来的节点角色那栏是空的，也就是说你 kubectl get nodes 看到的节点没有显示 master 或 worker 的标签。如果想跟常见教程输出保持一致，可以给节点打 label：

bash复制kubectl label node node01 node-role.kubernetes.io/worker=worker
kubectl label node node02 node-role.kubernetes.io/worker=worker

后续要多加节点，只要在新增机器上重复第 3 节的环境准备，再从 master 生成 join 命令执行就行。

6. 集群验收与一线排错经验

6.1 业务验证：部署 Nginx 并访问

集群搭完不等于万事大吉，建议立即部署一个测试应用，把整个链路跑通。先创建 Deployment：

bash复制kubectl create deployment nginx-test --image=nginx:1.25

等 Pod 起来：

bash复制kubectl get pods -o wide

看到 STATUS 是 Running 后，把它暴露成 NodePort 类型的 Service：

bash复制kubectl expose deployment nginx-test --type=NodePort --port=80
kubectl get svc nginx-test

输出的 PORT(S) 一栏会显示类似 80:32678/TCP，这个 32678 就是集群每个节点上监听的随机端口。然后随便找一台 node 的 IP，浏览器访问 http://192.168.1.11:32678，能看到 Nginx 默认页面就说明集群网络、调度、kube-proxy 全都正常工作。

我在实际验证中还喜欢把副本数扩到 3，看看 Pod 会不会被调度到多个 node：

bash复制kubectl scale deployment nginx-test --replicas=3
kubectl get pods -o wide

能看到三个 Pod 分布在 master01、node01、node02 不同的节点上，这才算真正体会到了“调度”的作用。

6.2 三个最常见现象的根因链路

这里记录几个我搭集群时反复遇到、也经常在社区看到的现象级问题。

现象一：coredns 一直在 ContainerCreating。执行 kubectl describe pod -n kube-system <coredns-pod>，如果报 sandbox 网络初始化失败，基本就是 CNI 插件没装或者装错了。确认 Flannel/Calico 的 Pod 都 Running 之后，coredns 会自己恢复。

现象二：node 节点加入后长时间 NotReady，且 kubectl describe node node01 里有 PLEG is not healthy 字样。这多半是容器运行时或 cgroup 驱动不稳定，检查 containerd 的 SystemdCgroup = true 配置，再确认系统内核参数是否生效。

现象三：kubeadm init 报 failed to get sandbox image "registry.k8s.io/pause"。这是镜像拉取失败，优先排查 DNS、镜像仓库可达性和代理设置。所有节点都要保证同一套网络出口，不要在 master 上能拉镜像，node 上却拉不动，否则后面调度到该节点就会卡在 ImagePullBackOff。

6.3 常用排查命令工具箱

排障不是靠猜，而是顺着链路用命令缩小范围。我整理了一套顺序：

bash复制kubectl get nodes                                  # 先看节点状态
kubectl get pod -A -o wide                         # 再看 Pod 分布
kubectl describe event --all-namespaces            # 快速看全集群事件
kubectl describe pod <pod-name> -n <namespace>     # 看单个 Pod 详情
journalctl -u kubelet -f                           # 看 kubelet 实时日志
journalctl -u kubelet -n 200 --no-pager           # 看最近 200 行

组合起来基本能覆盖 80% 的问题。Kubernetes 组件之间高度依赖网络和证书，报错信息经常会让人误判成配置问题，先看事件、再看日志、最后才动配置，这个顺序能少走很多弯路。

如果只是某个节点废掉，不要整个集群重来，直接：

bash复制kubeadm reset
rm -rf /etc/cni/net.d

把该节点清理干净，再重新 join。kubeadm reset 不会动其他节点，这是它作为部署工具最大的优势。reset 完如果还残留一些 pod 网卡，可以用 ip link show 检查，手动删除 flannel.1、cni0 这类虚拟网卡，避免重新 join 后网络插件初始化冲突。

搭建过程中我最大的感受是：k8s 集群搭建本身的难度并不高，难的是每一步都要知道自己为什么要这么做。版本锁没锁、swap 关没关、cgroup 驱动统一没统一、Pod 网段有没有和本机网段冲突，这些事情在刚开始可能看不出差别，等到节点多了、业务上来了，才会意识到前面任何一个偷懒都会在后续运维里加倍还回来。这套 kubeadm 流程我在多个环境里重复过很多次，只要按顺序准备好环境，再按同样的参数 init 和 join，成功率非常高。如果有条件，建议你搭完之后把 master 节点快照留一份，后续学什么组件、做什么实验都不用怕搞坏，直接回滚再搭一套就行。