手动搭一套 Kubernetes 集群，很多人第一反应就是难。尤其当你还要在它上面叠一个 KubeSphere，这个集可视化、多集群、监控、日志、DevOps 于一体的全家桶平台，光是版本匹配就够折腾一阵子。这篇文章写给想自己动手从裸机开始搭一套完整 k8s 环境的朋友，也写给公司内部要交付一个小团队可用平台、但又不想从零造轮子的人。整套流程在 CentOS 7.9 最小化安装环境上跑通，最终产出 k8s 1.23.17 + KubeSphere 3.4.1 的可用集群，中间涉及节点规划、运行时选型、网络方案、存储准备、平台安装，以及我认为比官方文档更有价值的踩坑记录。1. 动手前的整体设计与版本权衡1.1 为什么选 k8s 1.23.17 与 KubeSphere 3.4.1版本选型这件事，我吃过不少亏。最早图省事直接装最新版 k8s，结果碰上容器运行时、网络插件、监控组件一堆兼容性问题，排查成本反而更高。k8s 1.23.17 是个比较微妙的版本：它是最后一个还在支持 dockershim 的版本，但 1.24 之后 kubelet 已经默认移除对 Docker 的直接支持，很多还在用 Docker 的朋友在升级时被打了个措手不及。选 1.23.17 的好处在于，累了可以退一步用 Docker，往前又能顺利走上 containerd 这条路，兼容性上卡在了一个比较舒服的位置。KubeSphere 3.4.1 对 Kubernetes 版本的要求是支持 1.19 到 1.26，1.23.17 正好落在官方支持区间内，稳定性经过大量社区验证。如果选太新或者太旧的组合，安装 KubeSphere 时可能会遇到 API 版本不匹配、CRD 冲突之类的问题。我自己的建议是，除非你有更明确的需求，否则新手或者交付场景直接抄这组版本，省心程度比想象中高很多。1.2 节点规划与硬件配置参考我这次用的是三台机器：一台 master，两台 worker。IP 规划如下：角色主机名IP配置masterk8s-master192.168.10.314C8G，硬盘 50Gworkerk8s-worker1192.168.10.324C8G，硬盘 50Gworkerk8s-worker2192.168.10.334C8G，硬盘 50G如果只是做演示，单节点也可以，master 同时作为 worker 跑业务负载。但 KubeSphere 装完以后会有监控、日志、事件等一堆常驻组件，单节点 8G 内存会非常紧张，我实测过卡到 SSH 都延迟，所以至少准备 8G 内存，推荐 16G。另外，磁盘分区建议保留至少 30G 给/var/lib/containerd和/var/lib/kubelet，这两个目录是镜像层和容器数据的主战场。之前有个环境磁盘只有 20G，镜像拉多了直接No space left on device，排查了半天才发现是分区问题，很憋屈。1.3 网络与镜像仓库的提前规划Kubernetes 集群内部有三层网络要分清楚：节点网络、Pod 网络、Service 网络。节点网络就是你机器之间的互通网络，Pod 网络我按 Calico 的默认习惯留了10.244.0.0/16，Service 网络用10.96.0.0/12，这两个网段一定要跟现有物理网络错开，否则路由冲突会搞得人很崩溃。镜像仓库也需要提前想清楚。kubeadm 初始化时默认会从registry.k8s.io拉镜像，在国内网络环境下很容易卡住。我习惯把初始化配置里的imageRepository改成国内可用的镜像仓库地址，具体地址根据你自己环境来选，只要能稳定拉取就可以。这里强调一个原则：不在初始化过程中折腾网络，提前在配置阶段把镜像源搞定，后面会顺畅很多。2. 从零开始的基础环境准备2.1 操作系统初始化三板斧：主机名、防火墙、SELinux三台机器拿到手之后，第一步不是装 k8s，而是先把操作系统收拾干净。最小化安装的 CentOS 7.9 往往带着一堆默认配置，其中最容易出问题的就是 SELinux 和防火墙。先设置主机名，比如：hostnamectl set-hostname k8s-master hostnamectl set-hostname k8s-worker1 hostnamectl set-hostname k8s-worker2然后关闭 SELinux 和防火墙。这两个操作虽然在安全团队看来有点粗暴，但在内网交付场景里，为了减少 k8s 组件的流量被拦截、权限被限制的概率，我通常会先关掉：systemctl stop firewalld && systemctl disable firewalld setenforce 0 sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config接着关闭 swap。这一步很多人容易漏掉。kubelet 默认要求关闭 swap，否则启动时会报错。如果机器已经在跑其他服务不方便关 swap，也有折中方案，但最省事的就是直接关：swapoff -a sed -i '/ swap / s/^/#/' /etc/fstab注意：swapoff -a只是临时关闭，必须把/etc/fstab里的 swap 行注释掉，否则重启以后又自动挂载上了，kubelet 照样给你报错。2.2 时间同步与必要内核模块时间不同步会引发非常诡异的证书报错。k8s 组件之间大量使用 TLS 证书，节点时间偏差超过 5 分钟，证书校验失败，节点直接 NotReady，日志满天飞。CentOS 7 里我习惯用 chronyd：yum install -y chrony systemctl enable --now chronyd chronyc sources -v看到^*开头的行代表同步成功。这步别省，我都记不清踩过多少次时间坑了。然后加载两个内核模块，并写入开机加载配置：cat <<EOF | tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF modprobe overlay modprobe br_netfilter同时调整内核参数，让 iptables 能正确处理网桥流量：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 --systemip_forward = 1是 Kubernetes 网络转发的基础，没有它 Pod 之间的通信会断。这个参数在 Docker 环境下会自动开启，但用 containerd 的纯 k8s 环境经常会漏，务必检查。2.3 安装基础依赖包最后装一批通用依赖，避免后续装网络插件、存储插件时缺东少西：yum install -y yum-utils device-mapper-persistent-data lvm2 wget vim net-tools bind-utils其中yum-utils是后面配置 yum 源必需的。bind-utils里包含dig、nslookup等工具，排查 DNS 问题时特别有用，建议一起装掉。3. 容器运行时选型与 containerd 部署3.1 为什么我用 containerd 而不是 Dockerk8s 1.24 之后官方就把 dockershim 干掉了，到现在再来新装集群，继续用 Docker 作为运行时不仅要打补丁，还要面对一堆社区讨论得热火朝天的问题。containerd 本身就是容器标准实现的一部分，kubelet 直接通过 CRI 跟它通信，少了中间层，日志排查路径也短。KubeSphere 对 containerd 的适配非常成熟，官方安装文档里也是优先推荐这种方式。对于已经用惯 Docker 命令的人，过渡其实不难，你只需要记住crictl这个命令行工具。真正操作容器时用crictl ps、crictl logs、crictl exec，体验跟docker ps区别不大。3.2 containerd 的安装与配置使用 yum 安装 containerd：yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo yum install -y containerd.io安装完成后先生成默认配置：mkdir -p /etc/containerd containerd config default > /etc/containerd/config.toml这里有两个地方必须改。第一，开启 SystemdCgroup：[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] SystemdCgroup = true为什么要开这个？kubelet 和运行时之间关于 cgroup 驱动必须保持一致，kubelet 默认使用systemdcgroup 驱动，containerd 你也得把SystemdCgroup设为 true。不一致的时候，容器启动会报资源管理相关的错误，而且你查日志的时候大概率看不出来是这个原因。第二，修改 sandbox_image。这个镜像是每个 Pod 都会有基础 pause 容器，kubeadm 默认认为它在官方镜像仓库，国内拉不下来。我把sandbox_image改成可用的镜像仓库地址，比如：[plugins."io.containerd.grpc.v1.cri"] sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.6"改完以后重启 containerd：systemctl daemon-reload systemctl enable --now containerd systemctl restart containerd3.3 验证运行时是否真的可用配置完不能直接往后走，用crictl做个连通性测试：cat <<EOF | tee /etc/crictl.yaml runtime-endpoint: unix:///run/containerd/containerd.sock image-endpoint: unix:///run/containerd/containerd.sock timeout: 10 EOF crictl images如果crictl images能正常返回空列表，说明 CRI 通信没问题。我一开始忽略了配置crictl.yaml，命令行一直报找不到 containerd socket，其实是默认客户端连的是 Docker 的 socket，白白浪费了几分钟。实操心得：每次改完/etc/containerd/config.toml之后，一定执行containerd config --validate检查配置语法。有一次我只是少写了一个引号，整个服务直接起不来，排查了好久才发现是配置文件格式问题。4. 使用 kubeadm 初始化 Kubernetes 集群4.1 安装 kubelet、kubeadm、kubectl 并锁版本三台机器都需要装这三个组件。首先配置 yum 源：cat <<EOF | tee /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 EOF然后安装指定版本：yum install -y kubelet-1.23.17-0 kubeadm-1.23.17-0 kubectl-1.23.17-0安装完成后执行systemctl enable --now kubelet。此时 kubelet 大概率会启动失败，因为集群还没初始化，这是正常现象，不用慌。关键是不要让它被 yum 自动升级更新，否则版本漂移后谁也救不了你：yum -y install yum-plugin-versionlock yum versionlock kubelet kubeadm kubectl4.2 编写 kubeadm init 配置文件在 master 节点上写一个初始化配置：apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: 192.168.10.31 bindPort: 6443 nodeRegistration: criSocket: unix:///run/containerd/containerd.sock --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: v1.23.17 imageRepository: registry.aliyuncs.com/google_containers controlPlaneEndpoint: 192.168.10.31:6443 networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 --- apiVersion: kubeproxy.config.k8s.io/v1alpha1 kind: KubeProxyConfiguration mode: ipvs关于imageRepository，这里我直接写了国内可用的镜像仓库地址，初始化全程基本不需要额外等待太久。controlPlaneEndpoint我填了 IP，生产环境有条件的话可以填负载均衡地址或者域名。mode: ipvs是代理模式的选择，ipvs 性能比 iptables 好，支持更复杂的负载均衡策略，kube-proxy 在初始化的时候会用 IPVS 规则承载 Service 流量。4.3 初始化集群与节点加入执行初始化：kubeadm init --config kubeadm-config.yaml --upload-certs | tee kubeadm-init.log初始化结束后，末尾会输出两段重要信息：一段是配置 kubectl 的命令，一段是 worker 节点加入集群的命令。先配置本机访问：mkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config然后查看集群状态：kubectl get nodes此时 master 应该是NotReady状态，原因很简单：Pod 网络还没有就绪，这是正常的，下一步装完 CNI 插件就会变 Ready。在 worker 节点上，直接执行从日志里复制出来的kubeadm join命令。如果 token 过期或丢失，可以在 master 上重新生成：kubeadm token create --print-join-commandworker 加入成功后，在 master 上执行kubectl get nodes -o wide，应该能看到三台节点都出现在列表里，不过它们目前都会是 NotReady。4.4 关键参数的计算与调整思路podSubnet的选择要跟将来部署的 CNI 插件匹配。Calico 默认分配192.168.0.0/16，如果你初始化时写了别的网段，就必须修改 Calico 的配置让它跟你的指定网段一致。这里我统一用10.244.0.0/16，这个网段在社区里用得最多，跟各种网络插件都比较好配合。serviceSubnet是集群内部 Service 的虚拟 IP 网段，后续通过 kube-proxy 实现转发。它不会和 Pod 网段冲突，两者相互独立。如果这两个网段规划错了，后面部署任何应用都会出现路由不通、Service 无法访问之类的问题，而且排查起来非常麻烦，所以初始化配置时一定要一次写对。注意：初始化完成后如果想改这两个网段，基本只能重新初始化集群，所以动手前仔细确认，别偷懒。5. 部署 Calico 网络插件5.1 为什么选 CalicoCNI 插件可选的很多，Flannel 简单，Cilium 功能强，但我的推荐是 Calico。它对跨节点通信、NetworkPolicy 的支持都很成熟，性能也比 Flannel 好一些，是目前生产环境里覆盖率最高的方案之一。对于 k8s 1.23.17 这个版本，Calico v3.25 系列是验证过的组合。不用盲目追求最新版，稳定优先。5.2 安装与配置要点下载 Calico 清单：curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.25.1/manifests/calico.yaml打开calico.yaml，找到CALICO_IPV4POOL_CIDR这个环境变量，确认它跟我们初始化配置时的 Pod 网段一致：- name: CALICO_IPV4POOL_CIDR value: "10.244.0.0/16"如果不一致，Pod 会拿不到 IP 或者网络异常，表现为 Pod 一直ContainerCreating。改好之后直接应用：kubectl apply -f calico.yaml部署过程需要拉取镜像，尤其是 master 节点上calico-controllers和每台节点上的calico-node。用kubectl get pods -n kube-system -w观察，等所有calico-*Pod 变成 Running，再执行kubectl get nodes，这时三台节点应该都变成 Ready 了。5.3 验证网络是否真正打通节点 Ready 只是第一步，网络是否真的通还得做验证。建一个临时 Pod，跨节点访问一下：kubectl run test-pod --image=busybox -it --rm -- sh进入 Pod 后：ping 192.168.10.32 # 另一个节点的 Pod IP 或 Service IP不通的话先查 Calico Pod 日志。我遇到过的一种情况是 calico-node 启动时报错说无法检测到正确的网卡，原因是机器有多个网卡，Calico 自动选择了错误的那个做隧道。解决办法是给calico-node的容器添加环境变量，指定正确的网卡名，比如：env: - name: IP_AUTODETECTION_METHOD value: "interface=eth1"这个细节在官方文档里写得不明显，但真实环境中非常常见，尤其是有内网和公网双网卡的机器。6. 给 KubeSphere 准备存储底座6.1 KubeSphere 对存储的强依赖很多人觉得 KubeSphere 就是个面板，装上就完事了。实际上 KubeSphere 的监控、日志、事件、告警这些组件全部需要持久化存储。如果你没有提前准备好默认 StorageClass，ks-installer 装到一半会卡在某个组件一直 Waiting，等你发现再去补存储，又得折腾半天。验证集群当前有没有默认 StorageClass：kubectl get storageclass kubectl get sc --all-namespaces如果输出为空，就得先建一个。6.2 快速部署 local-path-provisioner生产环境通常上 Ceph 这种分布式存储，但演示环境不折腾这些，用 local-path-provisioner 就够了。它在每台节点上使用宿主机本地目录来提供 PV，部署快，清理也方便。下载并应用部署清单：kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.26/deploy.yaml这个清单会自动帮你创建local-pathStorageClass。然后把它设为默认：kubectl annotate storageclass local-path storageclass.kubernetes.io/is-default-class=true再查看一下：kubectl get storageclass输出里应该会有local-path，并且(default)字样。注意：local-path 存储有一个特点，就是每个 Pod 用到的 PVC 会绑定到 Pod 所在节点的本地目录。这意味着数据不会自动跨节点迁移。如果 Pod 被重新调度到别的节点，PVC 就会一直处于 Pending。演示环境无所谓，但生产环境一定要换集中式存储或分布式存储方案。7. 在已有 k8s 集群上部署 KubeSphere7.1 下载并应用 ks-installerKubeSphere 在已有集群上的安装方式很成熟，官方推荐的是 ks-installer。下载安装清单：kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/kubesphere-installer.yaml然后下载集群配置清单：kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/cluster-configuration.yamlcluster-configuration.yaml里主要定义的是 KubeSphere 核心组件的开关。默认情况下很多组件是关闭的，比如日志、监控、事件、告警这些都不一定是 enabled。你需要根据自己的需求去调整：kubectl edit clusterconfiguration ks-installer -n kubesphere-system比如把monitoring、logging、openpitrix（应用商店）改成enabled: true。不过我要提醒一句：功能开得越多，对资源的要求就越高。8G 内存的节点同时开监控和日志，我实测会有明显卡顿，所以按需开启、别一股脑全开。7.2 监控安装进度应用完配置后，ks-installer 会以 Deployment 形式跑起来，然后依次创建 KubeSphere 的各种组件和 CRD。看安装进度的方法：kubectl get pods -n kubesphere-system -w更直观的方式是看 ks-installer Pod 的日志：kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-install -o jsonpath='{.items[0].metadata.name}') -f日志里会滚动输出当前正在初始化的组件名。安装时长取决于镜像拉取速度和组件数量，网络正常的情况下 20 到 40 分钟比较常见。耐心点，如果中途卡住别急着重新安装，先看看具体卡在哪个组件上。7.3 安装完成标志与登录信息当安装完成时，日志末尾会打印一段信息：##################################################### Console: http://192.168.10.31:30880 Account: admin Password: P@88w0rd #####################################################KubeSphere 控制台默认通过NodePort: 30880对外提供服务。用浏览器访问这个地址，输入初始账号密码就能登录。登录后第一件事建议是右上角进入「平台管理」-「平台设置」，修改默认密码，毕竟默认密码是公开的。如果发现浏览器访问不了 30880 端口，优先检查防火墙。前面步骤我们已经关了 firewalld，但如果服务器上还有云安全组之类的策略，记得放行。集群内部的话可以用curl -I http://192.168.10.31:30880先自测。7.4 组件健康状态检查清单登录进控制台后，我习惯按下面列表过一遍：「集群管理」-「节点」：三台节点都要是健康状态。「集群管理」-「服务」：看 kubesphere-system 和 kubesphere-monitoring-system 命名空间里的服务有没有异常。「平台管理」-「基础组件」：检查 Istio、监控、日志这些是不是 ready。「工作台」-「企业空间」：创建一个企业空间，再创建项目，确保后续应用可以正常部署。如果某些组件显示不健康，回到命令行用kubectl get pods -n 对应命名空间把问题 Pod 找到，大概率事件是镜像拉取失败、资源不足或 PVC 没绑定，逐一排除即可。8. 全链路验证：让空集群真正跑起来8.1 部署一个典型应用验证网络与调度光有控制台界面还不够，我每次搭建完都要部署一个实际应用来验证链路是否完整。拿一个 Nginx 做测试：kubectl create deployment nginx-demo --image=nginx:1.23 kubectl expose deployment nginx-demo --port=80 --target-port=80 --type=NodePort查看服务暴露的端口：kubectl get svc nginx-demo输出里的30888:80类似格式表示宿主机上的 30888 端口被映射到 Service 的 80 端口。在任意节点上访问：curl http://192.168.10.31:30888能返回 Nginx 欢迎页就说明 Pod 创建、Service 转发、NodePort 访问这几条链路全通了。8.2 回到 KubeSphere 观察监控数据在 KubeSphere 控制台进入刚创建的项目，点击「工作负载」应该能看到nginx-demo这个 Deployment 的实时状态。点击「监控」页面，如果之前开启了监控组件，可以查看 CPU、内存、网络等图表。这里如果查询不到数据，先确认监控组件有没有正常采集指标，可以看 kube-state-metrics 和 node-exporter 相关 Pod 是否在运行。抛一个常见性能问题：KubeSphere 默认的监控数据保留周期是 7 天左右，数据量大的话对存储空间有要求。local-path 这种本地存储一般没啥问题，但要注意磁盘水位，满了以后监控组件会报错，而很多人只会看应用日志，忽略底层存储空间。8.3 验证日志查询链路进入「项目」下的「日志查询」页面，搜索一下刚才 Nginx Pod 的日志。如果日志功能是开启的，你不需要 SSH 到节点上敲命令，直接在控制台就能看到容器标准输出。这个功能在多节点环境里特别值钱，省掉了挨个节点翻日志的时间。如果日志查不到，大概率是 fluent-bit 或相关日志采集器没起来，先看对应命名空间的 Pod 状态。日志功能开起来之后，每台节点上的容器日志都会被采集到集群内部存储，注意做好索引和容量规划，别让日志无限堆积把磁盘塞满。9. 问题排查速查与避坑经验9.1 常见现象、根因与解决思路现象大概率原因排查路径kubelet 启动失败cgroup 驱动不一致 / swap 未关看journalctl -xeu kubelet日志，检查 fstabcontainerd 拉镜像超时sandbox_image 配置不对 / 网络受限修改 config.toml 里 sandbox_image 并重启节点一直 NotReadyCNI 插件没装好 / 网卡选择错误查 kube-system 里 calico Pod 日志Pod 一直 Pending没有可用 PVC / 资源不足看 Pod 事件kubectl describe pod xxxKubeSphere 安装卡 Waiting内存不足 / 没有默认 SC调整组件开关，确认 StorageClass 存在控制台访问不了 30880防火墙 / 安全组没放行本机 curl，检查 firewalld 状态容器跨节点不通Pod 网段冲突 / ip_forward 未开逐层 ping，查内核参数和 Calico 配置以上表格是我按问题频率大致排列的，前三条在整套流程中最容易出现。遇到问题不要急着重装集群，先把日志翻出来，对照现象定位，修复成本往往比重装低很多。9.2 初始化失败后的重开姿势有时候改来改去把集群搞乱了，最干净的办法是重置。kubeadm 提供了残留清理命令：kubeadm reset -f rm -rf /var/lib/calico /etc/cni/net.d /var/lib/cni /etc/kubernetes /var/lib/kubelet /var/lib/etcd在 reset 之后，再用初始化流程重新走一遍。如果是多节点集群，master 和 worker 都要做 reset。做完之后检查iptables -L -n和ipvsadm -Ln有没有残留规则，有的话清一遍。这个操作我在内部环境演示时经常用，也是面试里比较出色的亮点，省事且不容易留垃圾数据。9.3 证书与版本漂移的长期维护k8s 1.23.17 的证书默认有效期是 1 年，KubeSphere 本身也会生成自己的证书。半年之后你会突然发现某个组件开始报证书错误，这时直接用 kubeadm 自动续期：kubeadm certs renew all然后重启相关组件，别等证书真的过期再处理。另外，之前用yum versionlock把版本锁住了，后续如果要升级 k8s 小版本，先解锁再操作：yum versionlock delete kubelet kubeadm kubectl升级是对所有节点都要操作的，不能只动 master，顺序也要按照官方文档的指导来，先升级 kubeadm 和 kubelet，再升级 kubectl，避免版本不一致导致的 API 兼容问题。9.4 我反复实操后总结的几条心得第一，KubeSphere 组件开启顺序和资源规划直接挂钩。想开全功能，至少给 master 留 6G 空闲内存，worker 留 4G 空闲内存，不然安装过程会卡到想砸键盘。第二，local-path 这类本地存储确实方便，但换节点数据不跟随，所以演示可以，交付还是得按照业务需要设计持久化方案。第三，集群装完后立即把所有账号密码和证书备份信息记到本地，别等半年后再东翻西找。第四，所有 yaml 文件尽量走版本管理，git 里留一份，出了问题可以快速 diff 出谁动了配置。装完这套环境，你会明显感觉到一件事：Kubernetes 本身只是一个计算调度平台，真正让它变成一套“能交付、能运维、能监控”的系统，需要你把网络、存储、证书、资源规划统统串起来。KubeSphere 负责了视觉和交互上的最后一公里，但底下的每层配置，还是得自己心里有数。希望这篇文章能帮你少踩几个我踩过的坑。
手动搭一套 Kubernetes 集群，很多人第一反应就是难。尤其当你还要在它上面叠一个 KubeSphere，这个集可视化、多集群、监控、日志、DevOps 于一体的全家桶平台，光是版本匹配就够折腾一阵子。这篇文章写给想自己动手从裸机开始搭一套完整 k8s 环境的朋友，也写给公司内部要交付一个小团队可用平台、但又不想从零造轮子的人。整套流程在 CentOS 7.9 最小化安装环境上跑通，最终产出 k8s 1.23.17 + KubeSphere 3.4.1 的可用集群，中间涉及节点规划、运行时选型、网络方案、存储准备、平台安装，以及我认为比官方文档更有价值的踩坑记录。1. 动手前的整体设计与版本权衡1.1 为什么选 k8s 1.23.17 与 KubeSphere 3.4.1版本选型这件事，我吃过不少亏。最早图省事直接装最新版 k8s，结果碰上容器运行时、网络插件、监控组件一堆兼容性问题，排查成本反而更高。k8s 1.23.17 是个比较微妙的版本：它是最后一个还在支持 dockershim 的版本，但 1.24 之后 kubelet 已经默认移除对 Docker 的直接支持，很多还在用 Docker 的朋友在升级时被打了个措手不及。选 1.23.17 的好处在于，累了可以退一步用 Docker，往前又能顺利走上 containerd 这条路，兼容性上卡在了一个比较舒服的位置。KubeSphere 3.4.1 对 Kubernetes 版本的要求是支持 1.19 到 1.26，1.23.17 正好落在官方支持区间内，稳定性经过大量社区验证。如果选太新或者太旧的组合，安装 KubeSphere 时可能会遇到 API 版本不匹配、CRD 冲突之类的问题。我自己的建议是，除非你有更明确的需求，否则新手或者交付场景直接抄这组版本，省心程度比想象中高很多。1.2 节点规划与硬件配置参考我这次用的是三台机器：一台 master，两台 worker。IP 规划如下：角色主机名IP配置masterk8s-master192.168.10.314C8G，硬盘 50Gworkerk8s-worker1192.168.10.324C8G，硬盘 50Gworkerk8s-worker2192.168.10.334C8G，硬盘 50G如果只是做演示，单节点也可以，master 同时作为 worker 跑业务负载。但 KubeSphere 装完以后会有监控、日志、事件等一堆常驻组件，单节点 8G 内存会非常紧张，我实测过卡到 SSH 都延迟，所以至少准备 8G 内存，推荐 16G。另外，磁盘分区建议保留至少 30G 给/var/lib/containerd和/var/lib/kubelet，这两个目录是镜像层和容器数据的主战场。之前有个环境磁盘只有 20G，镜像拉多了直接No space left on device，排查了半天才发现是分区问题，很憋屈。1.3 网络与镜像仓库的提前规划Kubernetes 集群内部有三层网络要分清楚：节点网络、Pod 网络、Service 网络。节点网络就是你机器之间的互通网络，Pod 网络我按 Calico 的默认习惯留了10.244.0.0/16，Service 网络用10.96.0.0/12，这两个网段一定要跟现有物理网络错开，否则路由冲突会搞得人很崩溃。镜像仓库也需要提前想清楚。kubeadm 初始化时默认会从registry.k8s.io拉镜像，在国内网络环境下很容易卡住。我习惯把初始化配置里的imageRepository改成国内可用的镜像仓库地址，具体地址根据你自己环境来选，只要能稳定拉取就可以。这里强调一个原则：不在初始化过程中折腾网络，提前在配置阶段把镜像源搞定，后面会顺畅很多。2. 从零开始的基础环境准备2.1 操作系统初始化三板斧：主机名、防火墙、SELinux三台机器拿到手之后，第一步不是装 k8s，而是先把操作系统收拾干净。最小化安装的 CentOS 7.9 往往带着一堆默认配置，其中最容易出问题的就是 SELinux 和防火墙。先设置主机名，比如：hostnamectl set-hostname k8s-master hostnamectl set-hostname k8s-worker1 hostnamectl set-hostname k8s-worker2然后关闭 SELinux 和防火墙。这两个操作虽然在安全团队看来有点粗暴，但在内网交付场景里，为了减少 k8s 组件的流量被拦截、权限被限制的概率，我通常会先关掉：systemctl stop firewalld && systemctl disable firewalld setenforce 0 sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config接着关闭 swap。这一步很多人容易漏掉。kubelet 默认要求关闭 swap，否则启动时会报错。如果机器已经在跑其他服务不方便关 swap，也有折中方案，但最省事的就是直接关：swapoff -a sed -i '/ swap / s/^/#/' /etc/fstab注意：swapoff -a只是临时关闭，必须把/etc/fstab里的 swap 行注释掉，否则重启以后又自动挂载上了，kubelet 照样给你报错。2.2 时间同步与必要内核模块时间不同步会引发非常诡异的证书报错。k8s 组件之间大量使用 TLS 证书，节点时间偏差超过 5 分钟，证书校验失败，节点直接 NotReady，日志满天飞。CentOS 7 里我习惯用 chronyd：yum install -y chrony systemctl enable --now chronyd chronyc sources -v看到^*开头的行代表同步成功。这步别省，我都记不清踩过多少次时间坑了。然后加载两个内核模块，并写入开机加载配置：cat <<EOF | tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF modprobe overlay modprobe br_netfilter同时调整内核参数，让 iptables 能正确处理网桥流量：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 --systemip_forward = 1是 Kubernetes 网络转发的基础，没有它 Pod 之间的通信会断。这个参数在 Docker 环境下会自动开启，但用 containerd 的纯 k8s 环境经常会漏，务必检查。2.3 安装基础依赖包最后装一批通用依赖，避免后续装网络插件、存储插件时缺东少西：yum install -y yum-utils device-mapper-persistent-data lvm2 wget vim net-tools bind-utils其中yum-utils是后面配置 yum 源必需的。bind-utils里包含dig、nslookup等工具，排查 DNS 问题时特别有用，建议一起装掉。3. 容器运行时选型与 containerd 部署3.1 为什么我用 containerd 而不是 Dockerk8s 1.24 之后官方就把 dockershim 干掉了，到现在再来新装集群，继续用 Docker 作为运行时不仅要打补丁，还要面对一堆社区讨论得热火朝天的问题。containerd 本身就是容器标准实现的一部分，kubelet 直接通过 CRI 跟它通信，少了中间层，日志排查路径也短。KubeSphere 对 containerd 的适配非常成熟，官方安装文档里也是优先推荐这种方式。对于已经用惯 Docker 命令的人，过渡其实不难，你只需要记住crictl这个命令行工具。真正操作容器时用crictl ps、crictl logs、crictl exec，体验跟docker ps区别不大。3.2 containerd 的安装与配置使用 yum 安装 containerd：yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo yum install -y containerd.io安装完成后先生成默认配置：mkdir -p /etc/containerd containerd config default > /etc/containerd/config.toml这里有两个地方必须改。第一，开启 SystemdCgroup：[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] SystemdCgroup = true为什么要开这个？kubelet 和运行时之间关于 cgroup 驱动必须保持一致，kubelet 默认使用systemdcgroup 驱动，containerd 你也得把SystemdCgroup设为 true。不一致的时候，容器启动会报资源管理相关的错误，而且你查日志的时候大概率看不出来是这个原因。第二，修改 sandbox_image。这个镜像是每个 Pod 都会有基础 pause 容器，kubeadm 默认认为它在官方镜像仓库，国内拉不下来。我把sandbox_image改成可用的镜像仓库地址，比如：[plugins."io.containerd.grpc.v1.cri"] sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.6"改完以后重启 containerd：systemctl daemon-reload systemctl enable --now containerd systemctl restart containerd3.3 验证运行时是否真的可用配置完不能直接往后走，用crictl做个连通性测试：cat <<EOF | tee /etc/crictl.yaml runtime-endpoint: unix:///run/containerd/containerd.sock image-endpoint: unix:///run/containerd/containerd.sock timeout: 10 EOF crictl images如果crictl images能正常返回空列表，说明 CRI 通信没问题。我一开始忽略了配置crictl.yaml，命令行一直报找不到 containerd socket，其实是默认客户端连的是 Docker 的 socket，白白浪费了几分钟。实操心得：每次改完/etc/containerd/config.toml之后，一定执行containerd config --validate检查配置语法。有一次我只是少写了一个引号，整个服务直接起不来，排查了好久才发现是配置文件格式问题。4. 使用 kubeadm 初始化 Kubernetes 集群4.1 安装 kubelet、kubeadm、kubectl 并锁版本三台机器都需要装这三个组件。首先配置 yum 源：cat <<EOF | tee /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 EOF然后安装指定版本：yum install -y kubelet-1.23.17-0 kubeadm-1.23.17-0 kubectl-1.23.17-0安装完成后执行systemctl enable --now kubelet。此时 kubelet 大概率会启动失败，因为集群还没初始化，这是正常现象，不用慌。关键是不要让它被 yum 自动升级更新，否则版本漂移后谁也救不了你：yum -y install yum-plugin-versionlock yum versionlock kubelet kubeadm kubectl4.2 编写 kubeadm init 配置文件在 master 节点上写一个初始化配置：apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: 192.168.10.31 bindPort: 6443 nodeRegistration: criSocket: unix:///run/containerd/containerd.sock --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: v1.23.17 imageRepository: registry.aliyuncs.com/google_containers controlPlaneEndpoint: 192.168.10.31:6443 networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 --- apiVersion: kubeproxy.config.k8s.io/v1alpha1 kind: KubeProxyConfiguration mode: ipvs关于imageRepository，这里我直接写了国内可用的镜像仓库地址，初始化全程基本不需要额外等待太久。controlPlaneEndpoint我填了 IP，生产环境有条件的话可以填负载均衡地址或者域名。mode: ipvs是代理模式的选择，ipvs 性能比 iptables 好，支持更复杂的负载均衡策略，kube-proxy 在初始化的时候会用 IPVS 规则承载 Service 流量。4.3 初始化集群与节点加入执行初始化：kubeadm init --config kubeadm-config.yaml --upload-certs | tee kubeadm-init.log初始化结束后，末尾会输出两段重要信息：一段是配置 kubectl 的命令，一段是 worker 节点加入集群的命令。先配置本机访问：mkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config然后查看集群状态：kubectl get nodes此时 master 应该是NotReady状态，原因很简单：Pod 网络还没有就绪，这是正常的，下一步装完 CNI 插件就会变 Ready。在 worker 节点上，直接执行从日志里复制出来的kubeadm join命令。如果 token 过期或丢失，可以在 master 上重新生成：kubeadm token create --print-join-commandworker 加入成功后，在 master 上执行kubectl get nodes -o wide，应该能看到三台节点都出现在列表里，不过它们目前都会是 NotReady。4.4 关键参数的计算与调整思路podSubnet的选择要跟将来部署的 CNI 插件匹配。Calico 默认分配192.168.0.0/16，如果你初始化时写了别的网段，就必须修改 Calico 的配置让它跟你的指定网段一致。这里我统一用10.244.0.0/16，这个网段在社区里用得最多，跟各种网络插件都比较好配合。serviceSubnet是集群内部 Service 的虚拟 IP 网段，后续通过 kube-proxy 实现转发。它不会和 Pod 网段冲突，两者相互独立。如果这两个网段规划错了，后面部署任何应用都会出现路由不通、Service 无法访问之类的问题，而且排查起来非常麻烦，所以初始化配置时一定要一次写对。注意：初始化完成后如果想改这两个网段，基本只能重新初始化集群，所以动手前仔细确认，别偷懒。5. 部署 Calico 网络插件5.1 为什么选 CalicoCNI 插件可选的很多，Flannel 简单，Cilium 功能强，但我的推荐是 Calico。它对跨节点通信、NetworkPolicy 的支持都很成熟，性能也比 Flannel 好一些，是目前生产环境里覆盖率最高的方案之一。对于 k8s 1.23.17 这个版本，Calico v3.25 系列是验证过的组合。不用盲目追求最新版，稳定优先。5.2 安装与配置要点下载 Calico 清单：curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.25.1/manifests/calico.yaml打开calico.yaml，找到CALICO_IPV4POOL_CIDR这个环境变量，确认它跟我们初始化配置时的 Pod 网段一致：- name: CALICO_IPV4POOL_CIDR value: "10.244.0.0/16"如果不一致，Pod 会拿不到 IP 或者网络异常，表现为 Pod 一直ContainerCreating。改好之后直接应用：kubectl apply -f calico.yaml部署过程需要拉取镜像，尤其是 master 节点上calico-controllers和每台节点上的calico-node。用kubectl get pods -n kube-system -w观察，等所有calico-*Pod 变成 Running，再执行kubectl get nodes，这时三台节点应该都变成 Ready 了。5.3 验证网络是否真正打通节点 Ready 只是第一步，网络是否真的通还得做验证。建一个临时 Pod，跨节点访问一下：kubectl run test-pod --image=busybox -it --rm -- sh进入 Pod 后：ping 192.168.10.32 # 另一个节点的 Pod IP 或 Service IP不通的话先查 Calico Pod 日志。我遇到过的一种情况是 calico-node 启动时报错说无法检测到正确的网卡，原因是机器有多个网卡，Calico 自动选择了错误的那个做隧道。解决办法是给calico-node的容器添加环境变量，指定正确的网卡名，比如：env: - name: IP_AUTODETECTION_METHOD value: "interface=eth1"这个细节在官方文档里写得不明显，但真实环境中非常常见，尤其是有内网和公网双网卡的机器。6. 给 KubeSphere 准备存储底座6.1 KubeSphere 对存储的强依赖很多人觉得 KubeSphere 就是个面板，装上就完事了。实际上 KubeSphere 的监控、日志、事件、告警这些组件全部需要持久化存储。如果你没有提前准备好默认 StorageClass，ks-installer 装到一半会卡在某个组件一直 Waiting，等你发现再去补存储，又得折腾半天。验证集群当前有没有默认 StorageClass：kubectl get storageclass kubectl get sc --all-namespaces如果输出为空，就得先建一个。6.2 快速部署 local-path-provisioner生产环境通常上 Ceph 这种分布式存储，但演示环境不折腾这些，用 local-path-provisioner 就够了。它在每台节点上使用宿主机本地目录来提供 PV，部署快，清理也方便。下载并应用部署清单：kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.26/deploy.yaml这个清单会自动帮你创建local-pathStorageClass。然后把它设为默认：kubectl annotate storageclass local-path storageclass.kubernetes.io/is-default-class=true再查看一下：kubectl get storageclass输出里应该会有local-path，并且(default)字样。注意：local-path 存储有一个特点，就是每个 Pod 用到的 PVC 会绑定到 Pod 所在节点的本地目录。这意味着数据不会自动跨节点迁移。如果 Pod 被重新调度到别的节点，PVC 就会一直处于 Pending。演示环境无所谓，但生产环境一定要换集中式存储或分布式存储方案。7. 在已有 k8s 集群上部署 KubeSphere7.1 下载并应用 ks-installerKubeSphere 在已有集群上的安装方式很成熟，官方推荐的是 ks-installer。下载安装清单：kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/kubesphere-installer.yaml然后下载集群配置清单：kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/cluster-configuration.yamlcluster-configuration.yaml里主要定义的是 KubeSphere 核心组件的开关。默认情况下很多组件是关闭的，比如日志、监控、事件、告警这些都不一定是 enabled。你需要根据自己的需求去调整：kubectl edit clusterconfiguration ks-installer -n kubesphere-system比如把monitoring、logging、openpitrix（应用商店）改成enabled: true。不过我要提醒一句：功能开得越多，对资源的要求就越高。8G 内存的节点同时开监控和日志，我实测会有明显卡顿，所以按需开启、别一股脑全开。7.2 监控安装进度应用完配置后，ks-installer 会以 Deployment 形式跑起来，然后依次创建 KubeSphere 的各种组件和 CRD。看安装进度的方法：kubectl get pods -n kubesphere-system -w更直观的方式是看 ks-installer Pod 的日志：kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-install -o jsonpath='{.items[0].metadata.name}') -f日志里会滚动输出当前正在初始化的组件名。安装时长取决于镜像拉取速度和组件数量，网络正常的情况下 20 到 40 分钟比较常见。耐心点，如果中途卡住别急着重新安装，先看看具体卡在哪个组件上。7.3 安装完成标志与登录信息当安装完成时，日志末尾会打印一段信息：##################################################### Console: http://192.168.10.31:30880 Account: admin Password: P@88w0rd #####################################################KubeSphere 控制台默认通过NodePort: 30880对外提供服务。用浏览器访问这个地址，输入初始账号密码就能登录。登录后第一件事建议是右上角进入「平台管理」-「平台设置」，修改默认密码，毕竟默认密码是公开的。如果发现浏览器访问不了 30880 端口，优先检查防火墙。前面步骤我们已经关了 firewalld，但如果服务器上还有云安全组之类的策略，记得放行。集群内部的话可以用curl -I http://192.168.10.31:30880先自测。7.4 组件健康状态检查清单登录进控制台后，我习惯按下面列表过一遍：「集群管理」-「节点」：三台节点都要是健康状态。「集群管理」-「服务」：看 kubesphere-system 和 kubesphere-monitoring-system 命名空间里的服务有没有异常。「平台管理」-「基础组件」：检查 Istio、监控、日志这些是不是 ready。「工作台」-「企业空间」：创建一个企业空间，再创建项目，确保后续应用可以正常部署。如果某些组件显示不健康，回到命令行用kubectl get pods -n 对应命名空间把问题 Pod 找到，大概率事件是镜像拉取失败、资源不足或 PVC 没绑定，逐一排除即可。8. 全链路验证：让空集群真正跑起来8.1 部署一个典型应用验证网络与调度光有控制台界面还不够，我每次搭建完都要部署一个实际应用来验证链路是否完整。拿一个 Nginx 做测试：kubectl create deployment nginx-demo --image=nginx:1.23 kubectl expose deployment nginx-demo --port=80 --target-port=80 --type=NodePort查看服务暴露的端口：kubectl get svc nginx-demo输出里的30888:80类似格式表示宿主机上的 30888 端口被映射到 Service 的 80 端口。在任意节点上访问：curl http://192.168.10.31:30888能返回 Nginx 欢迎页就说明 Pod 创建、Service 转发、NodePort 访问这几条链路全通了。8.2 回到 KubeSphere 观察监控数据在 KubeSphere 控制台进入刚创建的项目，点击「工作负载」应该能看到nginx-demo这个 Deployment 的实时状态。点击「监控」页面，如果之前开启了监控组件，可以查看 CPU、内存、网络等图表。这里如果查询不到数据，先确认监控组件有没有正常采集指标，可以看 kube-state-metrics 和 node-exporter 相关 Pod 是否在运行。抛一个常见性能问题：KubeSphere 默认的监控数据保留周期是 7 天左右，数据量大的话对存储空间有要求。local-path 这种本地存储一般没啥问题，但要注意磁盘水位，满了以后监控组件会报错，而很多人只会看应用日志，忽略底层存储空间。8.3 验证日志查询链路进入「项目」下的「日志查询」页面，搜索一下刚才 Nginx Pod 的日志。如果日志功能是开启的，你不需要 SSH 到节点上敲命令，直接在控制台就能看到容器标准输出。这个功能在多节点环境里特别值钱，省掉了挨个节点翻日志的时间。如果日志查不到，大概率是 fluent-bit 或相关日志采集器没起来，先看对应命名空间的 Pod 状态。日志功能开起来之后，每台节点上的容器日志都会被采集到集群内部存储，注意做好索引和容量规划，别让日志无限堆积把磁盘塞满。9. 问题排查速查与避坑经验9.1 常见现象、根因与解决思路现象大概率原因排查路径kubelet 启动失败cgroup 驱动不一致 / swap 未关看journalctl -xeu kubelet日志，检查 fstabcontainerd 拉镜像超时sandbox_image 配置不对 / 网络受限修改 config.toml 里 sandbox_image 并重启节点一直 NotReadyCNI 插件没装好 / 网卡选择错误查 kube-system 里 calico Pod 日志Pod 一直 Pending没有可用 PVC / 资源不足看 Pod 事件kubectl describe pod xxxKubeSphere 安装卡 Waiting内存不足 / 没有默认 SC调整组件开关，确认 StorageClass 存在控制台访问不了 30880防火墙 / 安全组没放行本机 curl，检查 firewalld 状态容器跨节点不通Pod 网段冲突 / ip_forward 未开逐层 ping，查内核参数和 Calico 配置以上表格是我按问题频率大致排列的，前三条在整套流程中最容易出现。遇到问题不要急着重装集群，先把日志翻出来，对照现象定位，修复成本往往比重装低很多。9.2 初始化失败后的重开姿势有时候改来改去把集群搞乱了，最干净的办法是重置。kubeadm 提供了残留清理命令：kubeadm reset -f rm -rf /var/lib/calico /etc/cni/net.d /var/lib/cni /etc/kubernetes /var/lib/kubelet /var/lib/etcd在 reset 之后，再用初始化流程重新走一遍。如果是多节点集群，master 和 worker 都要做 reset。做完之后检查iptables -L -n和ipvsadm -Ln有没有残留规则，有的话清一遍。这个操作我在内部环境演示时经常用，也是面试里比较出色的亮点，省事且不容易留垃圾数据。9.3 证书与版本漂移的长期维护k8s 1.23.17 的证书默认有效期是 1 年，KubeSphere 本身也会生成自己的证书。半年之后你会突然发现某个组件开始报证书错误，这时直接用 kubeadm 自动续期：kubeadm certs renew all然后重启相关组件，别等证书真的过期再处理。另外，之前用yum versionlock把版本锁住了，后续如果要升级 k8s 小版本，先解锁再操作：yum versionlock delete kubelet kubeadm kubectl升级是对所有节点都要操作的，不能只动 master，顺序也要按照官方文档的指导来，先升级 kubeadm 和 kubelet，再升级 kubectl，避免版本不一致导致的 API 兼容问题。9.4 我反复实操后总结的几条心得第一，KubeSphere 组件开启顺序和资源规划直接挂钩。想开全功能，至少给 master 留 6G 空闲内存，worker 留 4G 空闲内存，不然安装过程会卡到想砸键盘。第二，local-path 这类本地存储确实方便，但换节点数据不跟随，所以演示可以，交付还是得按照业务需要设计持久化方案。第三，集群装完后立即把所有账号密码和证书备份信息记到本地，别等半年后再东翻西找。第四，所有 yaml 文件尽量走版本管理，git 里留一份，出了问题可以快速 diff 出谁动了配置。装完这套环境，你会明显感觉到一件事：Kubernetes 本身只是一个计算调度平台，真正让它变成一套“能交付、能运维、能监控”的系统，需要你把网络、存储、证书、资源规划统统串起来。KubeSphere 负责了视觉和交互上的最后一公里，但底下的每层配置，还是得自己心里有数。希望这篇文章能帮你少踩几个我踩过的坑。