做过企业里的多套 K8s 集群之后，我的体会是：k8s 集群部署这件事，真正难的从来不是敲那几条命令，而是敲命令之前要做的整体设计和环境判断。先想清楚用什么方式部署、选哪个网络插件、容器运行时和系统服务怎么配合、节点资源够不够，再动手敲命令，才能少走弯路。这篇文章就围绕企业项目实战里最基础的一步——k8s 集群部署——把从架构选型到落地的完整过程，以及我在实际环境里踩过的一些坑，摊开来讲。适合正在给公司搭内部集群、准备把东西往生产环境迁的同学，也适合已经能用 minikube 跑 demo、想进一步理解真实部署细节的朋友。
1. 部署前的整体设计
1.1 为什么企业项目首选 kubeadm
搭建 K8s 集群主流的路径有三条：二进制方式手动部署、kubeadm 方式、以及用云平台或商业发行版一键交付。纯二进制方式适合学习，需要自己下载并配置 kube-apiserver、kube-controller-manager、kube-scheduler、etcd、kubelet 等每一个组件，能让你把原理吃透，但确实维护成本高，一个证书、一个 systemd 单元错了都要排查半天。云托管方式虽然省事，但对很多企业内部环境来说不一定适用，尤其是要求网络隔离、数据不出机房、或者一套集群需要跨多环境统一运维的场景。
kubeadm 正好卡在中间：它是 Kubernetes 官方提供的基础部署工具，不是某个第三方封装的发行版。它会帮你生成控制面组件的静态 Pod 清单、签发证书、生成引导令牌，还能通过配置文件来控制版本、API Server 地址、Pod 网段和 Service 网段。对运维来说，kubeadm 最大的价值在于把整个部署过程变成了“配置文件 + 标准命令”，可重复、可审计、可升级。后续用 kubeadm upgrade 做版本升级，也比手工替换二进制稳妥得多。
我在实际项目中几乎都选 kubeadm，核心理由是它保留了足够的掌控力。你仍然可以知道每个组件以什么方式跑在哪个节点上，出了问题可以直接进节点看静态 Pod 目录；同时它又替你解决了证书、令牌这些繁琐内容，交付速度比纯二进制快好几个量级。
1.2 架构拓扑怎么定：单控制面起手，高可用打底
说到企业项目，很多人第一反应是“必须高可用”。这个想法没错，但也要看阶段。如果你刚把集群从测试环境推向生产，我建议第一版先做一套单控制面 + 多工作节点的标准集群，把业务、存储、网络这些模块先跑起来，再在第二个阶段引入多控制面高可用。原因很简单：高可用不只是多复制一台机器，还需要给 kube-apiserver 配 VIP 或负载均衡，etcd 要做三节点集群，证书配置、拓扑关系也完全不一样。一上来就揉在一起，出了问题很难判断是基础环境问题还是高可用组件问题。
当然，单控制面不意味着随便玩。至少在节点角色上要严格分清楚：控制面节点只跑系统组件和运维工具，不调度业务 Pod；工作节点专注跑业务负载。我在示例项目中会规划为一台控制面节点 + 两台工作节点，后续如果要扩展高可用，控制面节点可以增加到三台，工作节点也可以横向扩容。
规格上按一个基本标准来：控制面节点至少 4 核 8 G，磁盘 50 G 以上；工作节点建议 8 核 16 G，磁盘 100 G 以上。如果公司内部有更重负载的业务，存储、计算节点可以继续单独规划。这里有个很常见的误区，就是把 etcd 和控制面组件放在同一台配置很低的机器上。etcd 对磁盘 IO 和内存都敏感，一旦控制面节点资源不够，第一个掉链子的往往就是 etcd，表现为 apiserver 延迟飙高、节点反复失联。
1.3 CNI 选型：先想清楚网络再做集群
K8s 本身不实现容器网络，Pod 要互通、Service 要负载均衡、网络策略要做隔离，都得靠 CNI 插件。这个决定最好在部署前就定下来，因为很多网络插件会在集群初始化后以 DaemonSet 方式运行，如果你中途更换，要清理的东西很多。
业界常用的无非是 Flannel、Calico、Cilium 这三类。Flannel 是最容易上手的，VXLAN 模式在简单环境里很稳定，但功能也相对基础，NetworkPolicy 默认支持有限，性能上比路由模式有额外封装开销。Calico 是目前生产里最常见的选项，支持 BGP 路由直连和 VXLAN 两种模式，NetworkPolicy 是原生能力，性能稳定，资料也多。Cilium 走的是 eBPF 路线，性能和可观测性都强，但内核版本要求高，企业内部如果节点内核版本比较老，用起来会比较折腾。
我的建议很简单：没有特殊诉求就选 Calico，使用面广、问题容易搜到，和 kubeadm 默认的 Pod 网段也能很好配合。如果你所在的内网网络环境很简单，只是先验证功能，Flannel 也不是不行。但如果后续要大规模跑微服务，还要做细粒度网络策略，Cilium 可以留到验证过内核兼容性之后再考虑。选型不是越新越好，而是要和现有基础设施、团队维护能力匹配。
2. 前置准备与系统调优
2.1 节点规划和资源清单
动手之前把每台节点的角色、IP、主机名、操作系统列成一张表。比如我这次示例环境用的是三台内网机器：
控制面节点，主机名 master01，IP 192.168.10.10，操作系统为某 Linux 发行版，版本尽量选择社区支持周期内的长期支持版，4 核 8 G 起步。工作节点 worker01 和 worker02，分别 192.168.10.11 和 192.168.10.12，同样保持系统版本一致。
主机名这块要注意：不要带下划线，不要有大写，DNS 解析要干净。一个很通俗的比喻是，K8s 集群里的节点身份基本上靠主机名和证书里的 CN 来区分，如果主机名乱来，kubelet 注册节点时会出各种莫名奇妙的问题。我当时遇到过一次，节点加入集群后显示的名字和预期不一致，后来发现就是主机名带了特殊字符。
端口方面不是每个节点都要放通全部端口，但既然是企业内网，先统一放通基础端口也没问题。控制面节点需要 6443（apiserver）、2379（etcd 客户端端口）、2380（etcd 节点间通信）、10250（kubelet 指标接口）、10259（kube-scheduler）、10257（kube-controller-manager）等。工作节点主要放通 10250 和 30000-32767（NodePort 服务端口段）。如果用的是带安全组或防火墙的云内网环境，记得把同一个集群节点的对应网段互访加白。
2.2 基础环境配置
系统层面的准备工作，我习惯按下面几步来。
第一步，关闭 swap。K8s 从设计上要求节点关闭 swap，因为 kubelet 在内存管理上要依赖 cgroup 机制，如果启用了 swap，Pod 的内存限制会变得不可靠。关闭方式是swapoff -a，同时要把 /etc/fstab 里的 swap 行注释掉，否则重启机器后 swap 又回来了。这一步看着简单，但实际环境里很容易被忽略。
第二步，加载内核模块并调整系统参数。编辑 /etc/modules-load.d/k8s.conf，加入overlay和br_netfilter，然后执行modprobe overlay和modprobe br_netfilter。接着添加内核参数：
cat <<EOF | sudo 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 sudo sysctl --system这里面的逻辑是让 iptables 能处理网桥设备上的流量，否则基于 iptables 的 Service 转发规则不会生效。
第三步，如果系统启用了 SELinux，在非强制模式下运行。对 K8s 来说，SELinux 不是不能配合，而是需要配置合适的策略，很多系统默认策略并不会给容器运行时放行，导致 kubelet 和容器启动失败。所以我一般建议在部署集群的内网节点上将其设为 permissive 模式，这不是偷懒，而是在降低首套集群的排障范围。
第四步，时间同步。etcd 对时钟偏移很敏感，集群里所有节点的时钟差不能太大。用 systemd-timesyncd 也好，用独立 NTP 服务也好，都要确保是自动同步状态。
2.3 容器运行时安装与配置
现在 K8s 主流的容器运行时是 containerd，相比过去以 shim 方式对接 Docker 的链路，更轻量也更直接。企业新装集群，我建议直接用 containerd。
安装完成后，最重要的是修改配置里两个地方：cgroup driver 和 pause 镜像地址。
kubelet 默认使用 systemd 作为 cgroup driver，容器运行时也要保持一致，否则节点会一直报错。containerd 的默认配置可能在 /etc/containerd/config.toml，需要先生成一份默认配置再修改：
sudo mkdir -p /etc/containerd containerd config default | sudo tee /etc/containerd/config.toml找到SystemdCgroup这一行，改成SystemdCgroup = true。这个参数决定了容器内的进程如何被 cgroup 管理，kubelet 和运行时如果不一致，Pod 会一直创建不出来，或者内核日志里反复出现 unlink 错误。
pause 镜像是每个 Pod 启动前都会拉取的“沙箱”镜像，K8s 所有节点都要有这个镜像。如果你所在环境无法直接访问官方镜像仓库，就需要配置一个镜像仓库代理地址，或者提前手动把镜像导入节点。这里说明一下，生产环境里我更推荐用公司自建的镜像仓库作为代理，在 containerd 的 registry 配置段里填上registry.mirrors地址，也就是把所有外部镜像的统一拉取入口指向内网代理仓库。这样既稳定，也方便审计，比每台节点各自去外网拉取要靠谱得多。
配置完后重启 containerd，再执行crictl version验证。顺手把 crictl 的运行时端点配置好，因为后续排查问题时，crictl ps、crictl logs是高频命令：
cat <<EOF | sudo tee /etc/crictl.yaml runtime-endpoint: unix:///run/containerd/containerd.sock image-endpoint: unix:///run/containerd/containerd.sock EOF3. kubeadm 部署集群全流程
3.1 安装 kubeadm、kubelet、kubectl
三个软件要在所有节点上安装，其中 kubeadm 负责初始化和管理集群，kubelet 是节点上的核心服务，kubectl 是命令行工具，控制面节点和工作节点都需要，因为工作节点排查问题时也要用到。
版本一定要锁定。不能直接装 latest，因为当前 kubeadm 版本最多只支持比它新一个版本号的集群，如果你随便install到了非常新的版本，后面初始化时反而会报版本不匹配。我这里以 1.29 系列的某个小版本为例，配置 Yum 源或 Apt 源后执行：
sudo yum install -y kubeadm-1.29.1 kubelet-1.29.1 kubectl-1.29.1 sudo systemctl enable kubelet注意现在先不用启动 kubelet，等集群初始化后再启动，否则它找不到配置文件会一直报错。这句话我反复跟团队强调过，因为安装完成时默认服务可能处于启动状态，日志里一段时间内会疯狂刷错误，容易造成误判。
3.2 镜像预拉取与配置说明
如果网络环境一般，我强烈建议先手动预拉取集群组件镜像，而不是直接kubeadm init让它内部去拉。直接初始化的后果往往是命令卡在“waiting for the kubelet to boot”或者“unable to fetch image”，原因多半是镜像下载超时。
先用 kubeadm 查询当前版本需要的镜像列表：
sudo kubeadm config images list会得到像 kube-apiserver、kube-controller-manager、kube-scheduler、kube-proxy、pause 这样的镜像清单。然后手工拉取：
sudo kubeadm config images pull如果你配置了 containerd 的镜像仓库代理，这一步会自动走代理仓库下载。但要注意不同版本之间镜像名称可能变化，比如某个版本 pause 镜像的版本号又升级了，这时候重新执行kubeadm config images list确认即可。
我遇到过一种环境是节点之间虽然能互通，但所有机器都不能直接访问外部镜像仓库。这种情况下就需要在一台可以访问目标镜像源的机器上把镜像 pull 下来，再save成 tar 包，拷贝到每台节点后用ctr -n k8s.io images import导入。细节上要注意命名空间是k8s.io，导错命名空间的话 kubelet 依然找不到镜像。
3.3 控制平面初始化实操
初始化操作建议用一个配置文件来做，而不是直接敲一长串命令行参数。这样后续升级、变更、审计都有据可查。
先生成一个基础配置：
sudo kubeadm config print init-defaults > kubeadm-config.yaml然后编辑里面的关键字段。我通常只保留最核心的几个配置项：
apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: 192.168.10.10 bindPort: 6443 --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: "1.29.1" networking: podSubnet: "10.244.0.0/16" serviceSubnet: "10.96.0.0/12" controlPlaneEndpoint: "192.168.10.10:6443"解释几个关键点。
advertiseAddress是当前节点向集群公布的 IP 地址，如果你的机器有多个网卡，一定要显式指定，不然 apiserver 可能拿一个你不期望的网卡 IP。controlPlaneEndpoint在单控制面阶段先填这台节点自己的地址，后续做高可用时再改成负载均衡地址。podSubnet和serviceSubnet一定要提前规划，尤其 Pod 网段不能和公司内网已有的网段冲突，否则 Pod 路由一旦越过节点，可能会和真实服务器 IP 冲突。
确认配置没有问题后，执行初始化：
sudo kubeadm init --config kubeadm-config.yaml这个过程会做几件事：拉取并部署控制面组件静态 Pod、生成 PKI 证书、写出 kubeconfig 文件。看到类似输出提示kubeadm init complete时，就说明控制面起来了。按照提示执行下面几条命令配置 kubectl 的访问权限：
mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config然后验证一下：
kubectl get nodes这时的 master01 应该已经是 Ready 状态。如果显示 Ready 但组件还没完全就绪，可以等一两分钟再试。注意如果有节点不是 Ready，大概率是 CNI 还没安装，到了后面装了网络插件就会变好。
3.4 工作节点加入集群
控制面初始化完成后，输出里会有一行kubeadm join命令，带着一个 token 和证书哈希。这是最简单也最容易踩坑的一步，因为 token 默认 24 小时过期，很多人临时有事隔一天再回来，token 已经失效了。
如果 token 过期了，可以在控制面节点新生成：
sudo kubeadm token create --print-join-command拿到的命令复制到工作节点上执行。这里有一点很重要：工作节点上不要急着直接执行 join，先把镜像预拉取完成。因为kubeadm join执行时 kubelet 会在节点上拉取 kube-proxy 和 pause 镜像，如果拉取失败，节点加入过程会卡住。
工作节点执行完 join 后，回到控制面节点看节点状态：
kubectl get nodes kubectl get node -o wide如果节点状态一直是 NotReady，先看 CNI，再检查容器运行时日志。如果节点是 Ready 但 taints 没有被接受，业务 Pod 也不会被调度上来，后面还需要评估污点和容忍度配置。
3.5 安装 CNI 插件（Calico 为例）
这一步才是让 Pod 网络真正跑起来的关键。没有 CNI，控制面和所有工作节点之间的 Pod 网络都是不通的。
以 Calico 为例，需要下载对应版本的一套 manifest，它由很多资源对象组成：CRD、Controller、DaemonSet、RBAC 等。解压或下载后，一般要改动两处：一是 Pod 网段要和你规划的一致，二是网络模式。在 manifest 里搜索CALICO_IPV4POOL_CIDR，把值改成10.244.0.0/16。如果需要跨节点走 VXLAN 封装，就把IP_AUTODETECTION_METHOD和对应环境变量设置为 interface 匹配规则，确保 Calico 使用正确的网卡探测节点 IP。
然后执行：
kubectl apply -f calico.yaml安装完成后，观察 calico-system 命名空间下的 Pod：
kubectl get pods -n calico-system -w等所有容器 Running，等一会再看节点状态，应该就都是 Ready 了。验证方法很简单：创建一个临时 Pod，或者在任意命名空间部署两个测试 Pod，确认 Pod 之间 IP 能 ping 通。如果网络到了这一步还不通，优先排查节点上的 calico 日志：
kubectl logs -n calico-system <calico-node-pod>常见的原因包括节点 IP 探测到错误的网卡、BGP peer 配置错误、还有宿主机 IP 转发未打开。
4. 部署后必做的验证与配置固化
4.1 集群健康检查：节点、组件、Pod 三个维度
集群初始化完成、CNI 就绪之后，先别急着部署业务，一定要做一套完整的健康检查。
第一层是节点维度，kubectl get nodes看所有节点 Ready，kubectl describe node <node>看节点里面的 Conditions 和 Kubelet 状态。一个容易忽略的点是看NodePressure是否存在，比如磁盘或内存是否有压力。
第二层是组件维度，kubectl get pods -n kube-system检查所有控制面组件是否 Running 且 Ready。kube-apiserver、kube-controller-manager、kube-scheduler 这些组件如果反复重启，网络插件都救不回来。
第三层是运行时维度，随便起一个测试工作负载，比如：
kubectl run test-pod --image=busybox -- sleep 3600等 Pod Running 后进入容器，测试 DNS 解析和服务发现：
kubectl exec -it test-pod -- nslookup kubernetes.default.svc.cluster.local能解析就说明 kube-dns/coredns 是正常的。我再加一步测试，从 Pod 里访问 Service 的 ClusterIP，确认 kube-proxy 的转发规则没问题。
4.2 kubeconfig 与证书管理
K8s 对证书的依赖比大部分传统系统都强。kubeadm 默认生成的证书有效期一般是一年，这个到期时间在/etc/kubernetes/pki/目录下可以查出来：
openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates企业环境里最忌讳的就是用一年前配好的集群，突然某天 kubectl 报“证书过期或无效”。kubeadm 在工具升级时会自动处理一部分证书续期，但你不能指望它自动在某个时间点帮你做所有事。我一般建议：
- 把
/etc/kubernetes/pki/目录和 admin.conf 做一个定时备份，存到集群之外的位置； - 在监控系统里加一条证书过期时间检查；
- 如果集群要长期稳定运行，后续要考虑把证书续期纳入变更流程。
另外一个容易搞混的地方是 kubelet 客户端证书。kubeadm 部署的集群有 node bootstrapping 机制，节点 kubelet 会通过 token 申请自己的证书，正常情况下会自动轮转。但如果是在离线环境里手动导入的证书，就可能不会续期，节点某天会突然以 Unauthorized 的方式连不上 apiserver。这个坑我见过不止一次。
4.3 配置归档与文档沉淀
我强烈建议把集群初始化用的 kubeadm-config.yaml、CNI 的 manifest 版本、节点基础调优脚本、镜像拉取清单全部存到公司内部的代码仓库里。理由很实际：一套集群的交付过程不是跑几条命令就完了，后续任何人接手都要能按文档复现，或者起码知道每台机器上装了什么、改了哪些内核参数。
我会在部署完成后做几个固定动作：
- 把
kubeadm config view导出的内容保存到文档； - 把每个节点的 containerd 配置、系统参数配置收集到一个清单目录；
- 把本套集群的 Pod 网段、Service 网段、DNS 域名、节点 IP 规划写进资产表。
这样做的收益在半年后特别明显。之前有一次集群需要升级，团队成员需要确认当前版本和配置基线，直接翻开仓库里的配置一对比就知道改了什么，不用去一台一台机器上翻文件。
5. 常见问题与排查技巧实录
5.1 kubeadm init 超时的常见坑
kubeadm init 卡住，十次里八次都和镜像下载有关。控制面组件是静态 Pod，如果 kubelet 拉不到镜像，Pod 会一直处于 ContainerCreating，init 命令等不到 apiserver 健康检查通过，就会超时报错。
处理思路很简单：先别慌着反复重试 init，先看 kubelet 日志。
journalctl -u kubelet -f如果日志里明确写Failed to pull image ...，那就说明是镜像问题。按照前面说的预拉取流程，或者配置好镜像代理地址，重新拉取镜像，然后kubeadm reset后再 init。这里要注意kubeadm reset会清掉之前生成的配置和证书，属于正常操作，不要怕，但一定要确认这台机器上没有正在运行的业务数据。
还有一种情况是 apiserver 的 advertiseAddress 填了外部不可达的 IP，比如把内网 IP 填成一个不通的 VLAN 地址，节点内部组件之间都能访问，但从 kubelet 访问 apiserver 就是不通。所以初始化前先确认每个节点都能访问 192.168.10.10:6443，用telnet或nc -vz测一遍。
5.2 kubelet 启动失败该看哪
如果节点的 kubelet 起不来，第一件事永远是看 systemd 日志，而不是猜原因。常用命令是：
journalctl -u kubelet -n 100 --no-pager从日志里经常能看到三种典型错误。
第一种是failed to run Kubelet，后面跟unable to use swap space之类的信息。这就说明 swap 没有彻底关闭，回到节点上执行swapoff -a并注释 fstab。
第二种是 cgroup driver 不匹配。kubelet 报错里会出现failed to set cgroup config for ...，这时候检查 containerd 的SystemdCgroup是否改为 true，并且重启 containerd 后再重启 kubelet。顺序很重要，先运行时后 kubelet。
第三种是 kubelet 主配置找不到或目录权限不对。比如有人说怎么改 kubelet 里的配置没生效，其实要看 /var/lib/kubelet/config.yaml 这个文件，kubeadm 生成后不要把它的权限改成 777，否则 kubelet 出于安全校验会拒绝加载。
5.3 节点 NotReady 排查路径
节点 NotReady 是一个高频现象，出现的原因可能是网络插件、也可能是节点本身失联。我更倾向于先看节点状态详情：
kubectl describe node <node> | grep -A 10 Conditions在 Conditions 里，NodeReady的状态如果长期是Unknown或False，下一步分两条线查。
一条线是网络层面，从控制面节点 ping 工作节点、反向再 ping，确认三层通不通；再从控制面节点访问该节点的 10250 端口，确认 kubelet API 可以访问。如果 ping 得通但 10250 不通，检查防火墙和节点上 kubelet 监听地址是不是绑定到了错误网卡。
另一条线是 CNI 是否就绪。如果节点的 Ready 条件一直是 False 且原因是KubeletNotReady，报错信息里往往直接写着network is not ready。这时重点看该节点上 calico 或 flannel 的 Pod 是否 Running。很多时候你会发现某个节点上 CNI Pod 处于 CrashLoopBackOff，原因可能是内核版本低了、缺少某些 kernel module，或者网络插件选择的探测网卡不对。
我之前遇到最诡异的一次是 worker 节点上所有 Pod 都正常，但节点一直 NotReady，后来发现是 kubelet 的 node-ip 和一个现有物理网卡地址重复，导致健康检查流量走错了路径。最后在 /var/lib/kubelet/kubeadm-flags.env 里显式加了--node-ip参数才解决。
5.4 常用排查命令速查表
下表是我在实际运维时使用频率最高的几条命令，每次排查都从这些命令开始。
| 症状 | 排查命令 | 关键判断 |
|---|---|---|
| 节点状态异常 | kubectl get nodes && kubectl describe node | 看 Conditions 和 Kubelet 状态 |
| 控制面组件起不来 | kubectl get pods -n kube-system -o wide | 看 CrashLoopBackOff 或 ImagePullBackOff |
| kubelet 日志大量报错 | journalctl -u kubelet -n 200 --no-pager | 找 Failed to pull / cgroup / swap 关键字 |
| 容器运行时异常 | crictl ps && crictl logs | 看容器沙箱和运行状态 |
| Pod 一直 Pending | kubectl describe pod | 看 Events 里的调度限制、镜像拉取错误 |
| Service 通不了 | kubectl get endpoints && kubectl describe svc | 确认 Endpoint 是否有 Pod 地址 |
| DNS 解析失败 | kubectl get pods -n kube-system | grep coredns | 确认 CoreDNS Pod 与日志 |
| 证书异常 | openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates | 看证书过期时间 |
有一点要特别提醒，不要拿到一个 NodeNotReady 就直接去重启节点。先抓日志，再决定操作，很多时候问题根本不在节点本身，而是网络插件或 apiserver 连接问题，盲目重启只是把问题延后了。
我做完这套集群部署后印象最深的一点是：K8s 集群搭建本身是有套路可循的，真正的风险往往在那些不起眼的基础项上——镜像源、cgroup driver、内核参数、网卡探测、证书备份。每次新环境我都有个固定习惯，先在纸上画出节点拓扑和网段规划，再写部署命令，然后才开始执行。最后再用最小业务 Pod 做一次端到端验证，这个时候确认没过，后面的事才会顺利。
