1. 环境准备与方案选择先把话说在前头Kubernetes 1.26.4 这个版本不是最新版但它是一个经过了大量生产环境验证的稳定版本。如果你正在规划内部系统的容器化改造或者想搭建一套用于学习和测试的集群1.26.4 是一个很合适的选择。这个版本的 kubeadm 部署流程已经非常成熟网上资料也足够多遇到问题基本都能查到解决方案不会像追新版本那样踩到文档不全的坑。我这次部署采用的是标准的 kubeadm 方式没有用任何第三方封装工具。选择 kubeadm 的理由很简单它是 Kubernetes 官方提供的集群引导工具部署出来的集群最“干净”没有额外层层的封装后续排查问题、升级版本都更可控。而且 kubeadm 的部署逻辑非常清晰——先准备环境再装容器运行时然后初始化控制平面最后加入工作节点——这个流程搞明白了你对 Kubernetes 集群的架构理解会上升一个台阶。在开始之前先说一下我这次的实验环境方便你对照角色主机名配置系统控制平面节点master014核 8GBUbuntu 22.04 LTS工作节点1worker014核 8GBUbuntu 22.04 LTS工作节点2worker024核 8GBUbuntu 22.04 LTS提示如果资源有限可以缩减到 1 台控制平面节点加 1 台工作节点最低配置建议 2核 2GB但运行真实负载会比较吃力。生产环境建议 4核 8GB 起步。操作系统我选了 Ubuntu 22.04因为它的内核版本5.15对容器运行时的兼容性很好而且 containerd 的安装源在 Ubuntu 上是最省事的。当然 CentOS 7/8、Rocky Linux 也可以流程大同小异主要区别在防火墙配置和软件包管理命令上。整个部署流程预计耗时 30 到 60 分钟大部分时间花在拉取镜像和等待组件启动上。如果你对 Kubernetes 的基本概念Pod、Node、Deployment已经有一定了解这个部署过程会让你把这些抽象概念具象化——原来所谓的集群就是一堆组件各司其职通过 TLS 证书互相通信。2. 系统基础初始化系统初始化这部分最容易被忽略但恰恰是后面出问题最多的地方。我见过太多人在环境没准备好的情况下急匆匆执行 kubeadm init结果卡在各种奇怪的报错上最后发现是基础环境的问题。2.1 主机名与 hosts 解析每台机器需要设置唯一的主机名同时要确保集群内的机器能通过主机名互相访问。这步不做好后面 kubeadm join 的时候会报证书主机名不匹配的错误。在所有节点上执行# 设置主机名每台机器各自执行对应的 hostnamectl set-hostname master01 # 控制平面节点执行 hostnamectl set-hostname worker01 # 工作节点1执行 hostnamectl set-hostname worker02 # 工作节点2执行 # 所有节点都要配置 hosts 解析 cat /etc/hosts EOF 192.168.1.10 master01 192.168.1.11 worker01 192.168.1.12 worker02 EOF注意这里的 IP 地址要换成你自己的实际 IP。我用的网段是 192.168.1.0/24家庭实验环境比较常见。生产环境如果用到内部 DNS这里配置 DNS 解析也是一样的效果。2.2 关闭 Swap 与防火墙策略Kubernetes 在 1.26 版本中仍然强制要求关闭 Swap。原因有两个一是 kubelet 的 Pod 内存配额机制依赖 cgroup 控制如果系统启用 Swap内存限制可能被绕过二是调度器在做资源分配决策时不会把 Swap 计入可用内存这会导致节点过载的风险。# 关闭 swap swapoff -a sed -i /swap/s/^/#/ /etc/fstab # 加载内核模块 cat EOF | tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF modprobe overlay modprobe br_netfilter内核模块这块有个细节br_netfilter是保证 iptables 规则对 bridge 网络流量生效的关键模块。Kubernetes 集群的 Service 和 Pod 通信大量依赖 iptables/ipvs 规则如果这个模块没加载网络策略会静默失效表现就是跨节点 Pod 通信时通时不通非常难排查。继续配置内核参数cat EOF | 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 sysctl --systemnet.ipv4.ip_forward这个参数是很多人容易漏掉的。Kubernetes 的 Pod 网络需要开启 IP 转发否则跨节点的数据包会被内核丢弃。你可以用一个简单的方式验证如果集群内部 DNS 解析正常但 Pod 无法访问外部网络大概率就是这个问题。注意Ubuntu 默认的 ufw 防火墙如果开着建议先关闭以免干扰后续的网络配置。云服务器请在安全组放行 6443API Server、2379-2380etcd、10250kubelet等端口。我这里为了实验方便直接ufw disable了。3. 容器运行时的安装与配置Kubernetes 从 1.24 版本开始彻底移除了对 Docker 作为默认运行时的支持但注意这不影响你使用 containerd —— Docker 底层本来就是用 containerd 来做容器生命周期管理的。所以业界主流的方案是安装 containerd 作为 Kubernetes 的容器运行时同时不安装 Docker 全家桶。3.1 安装 containerd# 安装依赖 apt-get update apt-get install -y containerd # 生成默认配置文件 mkdir -p /etc/containerd containerd config default | tee /etc/containerd/config.toml这里有个必须调整的地方containerd 默认的 cgroup driver 是cgroupfs而 Kubernetes 推荐使用systemd作为 cgroup driver因为 systemd 在系统资源管理上更加稳定能避免双重 cgroup 管理的问题。编辑/etc/containerd/config.toml找到下面两处关键配置并修改[plugins.io.containerd.grpc.v1.cri] sandbox_image registry.aliyuncs.com/google_containers/pause:3.6 ... [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc] ... [plugins.io.containerd.grpc.v1.cri.containerd.runtimes.runc.options] SystemdCgroup true第一处是sandbox_image这是 Pod 的网络基础设施容器pause 容器的镜像地址。默认配置指向registry.k8s.io/pause:3.6这个地址在国内网络环境下可能拉取超时换成阿里云的镜像源会更稳定。这个镜像地址可以根据你自己的网络环境选择不强制。第二处是SystemdCgroup true这必须改。不改的话kubelet 健康检查会一直报错节点显示 NotReady。修改完后重启 containerdsystemctl restart containerd systemctl enable containerd systemctl status containerd3.2 安装 kubeadm、kubelet、kubectl这三件套的版本必须严格一致否则会出现兼容性问题。我的做法是直接指定版本安装apt-get update apt-get install -y apt-transport-https ca-certificates curl gpg curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.26/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.26/deb/ / | tee /etc/apt/sources.list.d/kubernetes.list apt-get update apt-get install -y kubelet1.26.4-00 kubeadm1.26.4-00 kubectl1.26.4-00 # 锁定版本防止意外升级 apt-mark hold kubelet kubeadm kubectl这里我额外提一句apt-mark hold的作用。Kubernetes 的版本演进非常快如果哪天不小心执行了apt-get upgrade三件套可能被自动升级到新版本导致集群组件版本不一致。锁定版本是个好习惯我见过不止一次因为这个问题导致的集群故障。4. 控制平面节点初始化所有基础环境准备好之后最关键的一步就是执行kubeadm init。这一步会完成 API Server、etcd、Controller Manager、Scheduler 等控制平面组件的初始化并生成集群的 TLS 证书和 kubeconfig 配置文件。4.1 预拉取镜像与初始化参数解析在正式初始化之前可以先预拉取需要的镜像这样初始化过程不会因为拉取镜像超时而中断# 查看需要哪些镜像 kubeadm config images list # 预拉取镜像 kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers--image-repository参数指定了镜像仓库地址。默认的registry.k8s.io在国外国内网络直连经常超时。替换为国内镜像源是一个稳妥的做法。这个参数在你后面的 kubeadm join 阶段同样需要保持一致。然后是核心的初始化命令kubeadm init \ --apiserver-advertise-address192.168.1.10 \ --control-plane-endpoint192.168.1.10 \ --image-repository registry.aliyuncs.com/google_containers \ --kubernetes-version v1.26.4 \ --pod-network-cidr10.244.0.0/16 \ --service-cidr10.96.0.0/12我来逐个解释这些参数--apiserver-advertise-address指定 API Server 对外通告的 IP 地址这里填控制平面节点的 IP。--control-plane-endpoint是集群的统一入口地址。单节点部署时直接填 IP 就行如果是高可用架构这里填负载均衡器的虚拟 IP 或域名。--pod-network-cidr是 Pod 网络的 CIDR 网段。这个参数必须与后面安装的 CNI 插件要求保持一致。我这里用的 10.244.0.0/16 是 Flannel 的默认网段如果你要装 Calico它的默认网段是 192.168.0.0/16两者不能混用。--service-cidr是 Service 虚拟 IP 的网段一般保持默认 10.96.0.0/12 即可这个网段只要不与你的物理网络冲突就行。4.2 初始化过程与配置初始化执行后你会看到一条明确的成功提示Your Kubernetes control-plane has initialized successfully!。如果卡住了大概率是镜像拉取问题或者网络问题可以查看 kubelet 日志定位journalctl -u kubelet -f成功初始化后按照输出提示配置 kubectlmkdir -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这时候你会看到控制平面节点的状态是NotReady。这是正常的因为还没有装 CNI 网络插件。同时初始化输出会给你一条kubeadm join命令里面包含了一个 bootstrap token 和证书哈希。请一定把这条命令保存下来后面加入工作节点要用。如果弄丢了也没关系可以在控制平面节点上用kubeadm token create --print-join-command重新生成。提示关于 kubeconfig 文件admin.conf包含了完整的集群管理员权限一定要保护好。后续运维工具比如 Dashboard、kubectl 远程访问都会用到这个文件。5. CNI 网络插件安装与节点加入5.1 安装 Flannel 网络插件网络插件是 Kubernetes 集群能正常工作的前提。没有 CNIPod 无法分配 IP节点之间也无法通信。我这里选了 Flannel原因是它足够简单、资源占用低适合中小规模的集群。kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml如果服务器无法直接访问 GitHub可以先把这份 YAML 文件下载到本地然后kubectl apply -f kube-flannel.yml。等 Flannel 的 Pod 全部启动后再查看节点状态kubectl get nodes kubectl get pods -n kube-flannel正常情况下节点状态会在一两分钟内变成Ready。如果长时间处于NotReady大概率是 Flannel 和 kubelet 的 cgroup driver 配置不一致或者内核模块没加载。5.2 工作节点加入集群工作节点的环境准备和控制平面节点基本一样需要完成第 2 节和第 3 节的所有步骤。唯一的区别是不需要安装 kubectl可选然后在工作节点上执行刚才保存的kubeadm join命令kubeadm join 192.168.1.10:6443 \ --token xxxxxx.xxxxx \ --discovery-token-ca-cert-hash sha256:xxxxxx执行成功后在控制平面节点上确认kubectl get nodes可以看到所有的节点都变成 Ready 状态。5.3 验证集群功能到这里一个最基础的 Kubernetes 集群已经搭好了。我习惯跑一个完整的测试来确认集群真的在工作# 部署一个测试应用 kubectl create deployment nginx --imagenginx:alpine kubectl expose deployment nginx --port80 --typeNodePort # 查看状态 kubectl get pods -o wide kubectl get svc nginx如果 Pod 正常运行Service 也分配到了 NodePort 端口用浏览器访问http://任意节点IP:NodePort端口能看到 Nginx 的欢迎页说明集群完全正常。6. 部署过程中的典型问题与排查思路我在部署和维护 Kubernetes 集群的过程中积累了不少踩坑经验。这里记录几个出现频率最高的问题你在部署时大概率也会遇到。6.1 节点一直 NotReady 的排查路径这是最常见的故障原因可能有好几种。先看 kubelet 日志定位journalctl -u kubelet -f常见的报错包括failed to get sandbox image registry.aliyuncs.com/google_containers/pause:3.6说明 pause 镜像拉取失败而没有配置 sandbox_image。检查 containerd 配置文件里的镜像地址是否修改正确。kubelet is misconfigured: kubelet cgroup driver: systemd is different from docker cgroup driver: cgroupfs说明 containerd 和 kubelet 的 cgroup driver 不一致回去检查 containerd 配置里 SystemdCgroup 是否已设置为 true。node not found或证书相关的错误说明初始化时使用的主机名和节点实际主机名不匹配检查 hosts 配置和 kubeadm init 参数。6.2 镜像拉取超时问题国内部署 K8s 集群镜像拉取超时是最大的拦路虎。除了前面提到的替换镜像仓库外还有两种情况第一种是 containerd 默认使用registry.k8s.io作为 sandbox 镜像地址如果你的网络环境无法访问需要在 containerd 配置文件里全局替换。我用的是阿里云的镜像源这一步在第三部分已经说过。第二种是当你使用某些私有镜像仓库时containerd 默认使用 HTTPS 连接。如果你的私有仓库只支持 HTTP需要在 containerd 配置里添加[plugins.io.containerd.grpc.v1.cri.registry.mirrors.my.registry.com]的配置并设置endpoint。6.3 Token 过期与重新生成kubeadm 默认生成的 token 有效期是 24 小时。如果你隔了很久才把工作节点加入集群token 已经失效执行 join 会报token is invalid的错误。解决方法是在控制平面节点上重新生成# 重新生成 token默认有效期 24 小时 kubeadm token create --print-join-command # 如果你希望 token 永不过期需要谨慎使用 kubeadm token create --ttl 0 --print-join-command同时还需要生成新的 discovery token CA 哈希openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2/dev/null | openssl dgst -sha256 -hex | sed s/^.* //把哈希值拼到 join 命令中格式为--discovery-token-ca-cert-hash sha256:哈希值。6.4 Pod 跨节点通信异常的排查思路这类问题的隐蔽性比较强表面现象是集群状态正常但 Pod 之间无法通信。我建议按下面的顺序排查# 1. 查看 CNI 插件 Pod 是否正常运行 kubectl get pods -n kube-flannel # 2. 检查节点路由表Flannel 会在每个节点上创建路由 ip route | grep flannel # 3. 检查 iptables 规则是否正常 iptables -L -n | grep FORWARD一个常见的原因是net.bridge.bridge-nf-call-iptables没有设置为 1导致 bridge 网络的流量没有经过 iptables 规则过滤。另外如果某个节点的 Flannel Pod 反复重启检查节点的 MTU 设置和内核模块尤其是使用了多网卡或者虚拟化网络时。7. 升级与维护的扩展思考集群搭建完成之后后续的升级维护也是绕不开的话题。这里分享一点我个人的经验和思路。关于版本升级Kubernetes 的升级路径是分步走的不能跳跃1.26.4 可以升级到 1.26.x 的最新补丁版本然后按顺序升级到 1.27.x、1.28.x。具体到操作上先升级 kubeadm 到目标版本然后执行kubeadm upgrade plan查看升级计划确认无误后执行kubeadm upgrade apply。这个流程我建议先在测试环境完整走一遍再上生产。关于证书续期控制平面组件的证书有效期是一年。在证书到期前三个月kubeadm 会给出警告。你可以执行kubeadm certs check-expiration查看各个证书的到期时间。1.26 版本支持证书自动续期但前提是控制平面组件的证书是由 kubeadm 管理的。如果是手动管理的证书需要手动处理时间充裕不需要焦虑。关于集群备份etcd 是整个集群的状态存储是最关键的备份对象。我建议定期使用etcdctl snapshot save做快照备份。你可以把这个操作写成一个 cron 脚本每天自动备份同时在升级前手动做一次完整的快照——这是性价比最高的灾备手段。最后说一句实战中最深的感受部署 Kubernetes 集群本身并不难难的是理解每个组件为什么这样设计、每个参数为什么这样配置。当你真正理解了 kubeadm init 背后做的那些事情后续不管是排障还是优化都会从容很多。希望这份指南能帮你顺利搭建起第一套属于自己的 Kubernetes 集群。