做运维的朋友都清楚Kubernetes的架构概念虽然不难理解但真正把集群跑起来的那一步劝退了不少人。手动二进制部署流程长、参数多证书、etcd、网络插件全部要自己来出个错能排查一下午用kubeadm集群能起了可后面装网络、装存储、装可视化管理界面又是一地鸡毛。所以我在一组测试环境里改用KubeKey从零拉一套k8s集群顺手把KubeSphere那套UI控制台也装上去。整个过程接近一体化不用手工做证书、不用单独部署etcd、不用再去翻dashboard文档。这篇文章适合刚接触k8s、想快速获得一套可用集群的人也适合公司内网环境里要交付多节点集群的运维同行参考。1. 先理解这套组合KubeKey和KubeSphere分别解决什么问题1.1 KubeKey不是一个“花哨的安装脚本”KubeKey本质上是KubeSphere社区维护的一款开源部署工具用Go语言写的单文件、无依赖下载下来就是一个可执行二进制。它最核心的能力是把“部署一套标准化K8s集群”这件事变成一条命令同时还能在同一个流程里把KubeSphere控制台一并装好。需要注意它不是包在Kubernetes外层的壳而是真正帮你完成底层的系统初始化和编排动作。具体来说KubeKey会自动处理以下几件原来要手动做的事生成etcd、kube-apiserver、kube-controller-manager、kube-scheduler等组件的证书和配置在目标机器上安装并配置容器运行时默认支持Docker和containerd把etcd集群、master控制面、worker工作节点按角色分组部署到位安装并配置Kubernetes核心组件包括kubelet、kubeadm、kubectl、kube-proxy自动选择网络插件默认使用Calico执行完上述步骤后再启动KubeSphere的初始化流水线。在KubeKey出现之前要达到同样的效果要么用kubeadm一字一字敲要么直接用别人封装好的脚本但那些脚本往往绑定了某一套固定环境不灵活。KubeKey区别最大的一点是配置文件是显式的、可审查的、YAML格式的生成之后可以对照检查每一台机器的IP、用户名、角色、密码还能在安装前手动调整。1.2 KubeSphere不是“又一个Dashboard”很多朋友第一次看到KubeSphere会觉得它不过是一个界面好看一点的Kubernetes Dashboard。实际用它一阵子之后会明白它的定位更接近“云原生管理系统”或“全栈管理控制台”不只是看Pod状态那么简单。KubeSphere里可以管理多租户、做DevOps流水线、查看全集群监控日志、创建应用商店、做灰度发布、管理服务治理和链路追踪。这些能力如果要在原生的Kubernetes上实现需要自己把监控、日志、告警、流水线、可视化等一堆组件拼起来运维成本不低。KubeSphere把这些常见能力集成在一起对不想重复造轮子的团队来说价值非常直接。而且它支持多集群管理。如果公司后续规划多个k8s集群或需要把开发环境和生产环境隔离KubeSphere能当作一个统一入口不用在多个Dashboard之间来回切换。这也是我把KubeSphere直接装在k8s集群上面的原因之一。1.3 谁适合照着这篇文章来做我最推荐两类人参考刚入门k8s需要一个“活着的集群”来实践学习。通过安装过程观察KubeKey、kubernetes组件如何组织比看文档再手动敲命令效率高很多。在测试环境、预发布环境里需要快速交付集群的运维或开发工程师。比如部门临时要一套环境做压测、做POC用KubeKey几分钟能解决还可以反复销毁重建。如果你是要给大型生产环境搭建极度定制化、合法合规的集群那本文方案可以当作起点参考但建议你对配置文件、网络方案、存储方案再做更深入的定制。另外如果只想要一个轻量的、纯学习K8s的集群那单机模式其实就够了但本文讲的是多节点完整集群操作上必须按步骤走。2. 部署前的环境准备硬件、系统、网络这三个坑请提前避开2.1 硬件与系统底线KubeSphere官方给出的推荐配置是至少3台机器每台2核4G以上这可真不是随便写的。实际部署时如果只有3台机器且每台都是2核4G跑起来之后你会发现资源吃紧尤其是装完KubeSphere之后etcd、Jenkins等组件常驻负载不低。我的建议是测试学习3台机器每台2核4G起步能跑 如果要同时做应用部署和流水线实验建议4核8G会舒服很多。生产负载较高的环境master节点建议4核8G以上worker节点根据业务量单独规划。磁盘系统盘至少50GKubernetes的镜像、容器日志、etcd数据都很占空间如果你磁盘只有20G装完KubeSphere很快会出现Evicted。操作系统层面我试过CentOS 7.9和Ubuntu 20.04都能顺利装好。CentOS 7需要注意内核版本默认3.10内核也能跑但如果要做更完整的网络和存储实验建议内核升到4.18以上。Ubuntu 20.04自带内核5.4默认就挺好用。2.2 节点拓扑与网络规划安装前先把拓扑想清楚。一个基础集群至少要分三块etcd节点存集群状态control-plane节点kube-apiserver、controller-manager、schedulerworker节点实际跑业务Pod。KubeKey允许一组机器同时承担多个角色。最简单的方式就是三台机器master节点同时承担etcd和control-plane其余两台作为worker。后面扩缩容时再把worker增加。网络规划必须提前做不要在装到一半才去改。注意以下几点三台机器之间内网互通SSH端口默认为22如果改过端口号要在config里明确指定。内网网段的划分要留出Kubernetes的Pod网段和服务网段默认情况下分别是10.233.0.0/18和10.233.64.0/18如果公司内网正好用了这个网段必须改掉否则路由全乱。提前确认各机器没有多条默认路由或网卡冲突的情况否则会让kubelet的node信息异常。2.3 基础环境初始化防火墙、主机名、时间同步这里是我最想提醒大家的部分。很多人机器本身没装好结果在KubeKey这一步就卡住报错还看不懂。请提前做以下几步第一关闭防火墙或放行必要端口。KubeKey安装过程需要通过SSH做免密登录、传输文件、启动服务防火墙不关经常出现连接被拒。CentOS上建议先systemctl stop firewalld并systemctl disable firewalld。对于生产环境不能简单关闭防火墙的话参考官方文档放行Kubernetes和KubeSphere所需端口但测试环境直接关掉最省事。第二检查hostname。Kubernetes集群要求各节点主机名不能重复且不能包含下划线。可以设置成k8s-master01这种风格注意不要使用带点号的完整域名某些情况下会让集群内部解析产生奇怪问题。第三主机名解析。编辑/etc/hosts把三台机器的IP和主机名对应关系写进去这一步很重要。KubeKey在部分阶段会在节点上执行命令解析集群主机名如果解析失败或者用了默认的localhost后面etcd集群会一直报通信错误。第四时间同步。etcd对时间偏移非常敏感。务必确保所有节点时区一致且时间源一致最简单的方式是配置NTP或Chrony定时同步。测试环境至少也要保证三台机器时间误差很小否则会出现“leader丢失”“连接被拒绝”之类的奇怪问题。第五关闭swap。Kubernetes要求宿主机关闭swap一行命令搞定swapoff -a随后把/etc/fstab里的swap挂载行注释掉。KubeKey其实不强制检查到严格程度但留着swap会在生产环境埋下性能和安全问题。我不想让这一步看起来过于繁琐但现实就是这样前面5分钟的准备能避免后面1小时甚至一下午的排障。我实际部署时有一次就是因为hostname里有个下划线导致KubeKey向节点分发挥作用时怎么都连不上排查了很久才发现是名字规范问题。3. 用KubeKey拉起K8s集群的完整实操3.1 下载KubeKey别为一条命令卡住KubeKey的下载方式有两种。一种是直接拉取二进制脚本再解压curl -sfL https://get-kk.kubesphere.io/download/v3.0.7 | tar -xz -执行完之后当前目录会多出一个kk可执行文件。记得给它加权限chmod x kk另一种是从GitHub Release页面下载对应平台的压缩包解压后是一样的。由于这个文件下载地址在某些网络条件下可能不稳定如果下载超时建议先尝试配置代理镜像或者在内网环境中使用提前下载好的压缩包分发到目标机器上。这里有个小技巧即使目标机器不能访问外网只要有一台机器可以下载把kk文件拷贝过去就能离线执行。下载完可以先看一眼版本号./kk --version如果正常输出版本信息工具就没问题。注意KubeKey是一个不依赖运行时环境的二进制不需要预先安装Go或Python这也是它能在很多裸机上快速上手的原因。3.2 生成配置文件每一行都要看懂KubeKey官方推荐的做法是先通过模板生成配置文件修改后再执行。执行下面的命令./kk create config --with-kubernetes v1.23.10 --with-kubesphere v3.3.0这个命令的含义是生成一个KubeKey部署配置文件config-sample.yaml并把Kubernetes版本固定为1.23.10KubeSphere版本固定为3.3.0。create config不会真正创建集群只是把待部署的信息先写出来。打开config-sample.yaml之后重点关注两头spec: hosts: - {name: k8s-master01, address: 192.168.10.11, user: root, password: YourPassword, arch: amd64, os: centos_7} - {name: k8s-node01, address: 192.168.10.12, user: root, password: YourPassword, arch: amd64, os: centos_7} - {name: k8s-node02, address: 192.168.10.13, user: root, password: YourPassword, arch: amd64, os: centos_7} roleGroups: etcd: - k8s-master01 control-plane: - k8s-master01 worker: - k8s-node01 - k8s-node02必改项包括address节点真实IPpasswordSSH登录密码namehostname必须和节点上实际设置一致os当前系统类型如果是Ubuntu就写ubuntu。如果SSH端口不是22可以在hosts项里加一个port: 2222。如果要使用SSH密钥而不用密码可以换成privateKeyPath字段指向私钥路径。如果只是想装K8s不装KubeSphere可以把--with-kubesphere参数去掉只生成一个纯K8s的配置。反过来集群已经跑起来了再想补装KubeSphere也不需要重新建集群后面我会说到这个用法。3.3 执行安装参数怎么选日志怎么读配置文件确认无误后运行./kk create cluster -f config-sample.yaml也可以不指定文件直接通过命令行参数创建集群./kk create cluster --with-kubernetes v1.23.10 --with-kubesphere v3.3.0但正在生产或正式测试环境里我更推荐文件方式因为你可以反复检查基础设施信息避免手滑输错密码或IP。执行之后KubeKey会先自动检测节点SSH连通性再逐阶段执行初始化。整个过程从SSH检查、节点系统配置、容器运行时安装、etcd部署、control-plane部署到worker加入需要一段时间。通常三节点集群在2.4G内存和普通SSD的机器上完成全部安装需要10到20分钟如果每台机器配置不高或者网络条件较差时间会明显变长要有耐心。执行过程中日志不停滚动如果中间卡住日志会最多显示到某个阶段名。KubeKey在出现问题时会给出Summary信息同时详细日志写入了/var/log/kubekey/install.log这是排障的第一现场。后面等我讲常见问题时还会重点用这份日志。注意几个关键阶段名TaskSSHPreCheck检查SSH连接和节点准备状态TaskInitK8sCluster初始化Kubernetes集群主要是证书和kubeadm相关TaskInstallKubeSphere在K8s上安装KubeSphere。如果在早期阶段就报错多半是SSH、网络、主机名之类的基础问题如果到了后面才失败大概率是镜像拉取超时或资源不足。不用一开始就去怀疑KubeKey本身有问题它的自我检测和报错逻辑已经比较完善。3.4 集群验证别急着装控制台安装成功后控制台会显示类似“Congratulations”或者“Successful”的文字但先别急着高兴建议做一次系统验证。KubeKey已经把kubectl配置到了执行机器的当前用户目录下直接执行kubectl get nodes正常情况会看到三台节点全部Ready其中master是control-plane,master角色另外两台是worker角色。再检查核心组件kubectl get pod -A重点看kube-system命名空间下的几个Pod是否Running例如etcd、kube-apiserver、kube-controller-manager、kube-scheduler、calico-kube-controllers、calico-node。任何一个不是Running或Ready都需要进一步查看。这步验证很关键不要跳过去后续装KubeSphere依赖集群本身健康。同时建议测试一下集群DNS是否正常工作kubectl run -it --rm debug --imagebusybox:1.28 nslookup kube-system能正确解析出ServiceName说明集群网络和CoreDNS是健康的。4. 装好K8s之后再接KubeSphere控制台4.1 两种路径一步到位还是事后补装KubeSphere安装在KubeKey的体系里有两种典型路径。路径一创建集群时直接带上KubeSphere./kk create cluster -f config-sample.yaml此时只要config-sample.yaml中addons或kubesphere相关参数正确KubeKey会在Kubernetes集群初始化完成后自动执行KubeSphere安装器把KubeSphere的所有组件都跑起来。这是最省事的方式。路径二Kubernetes集群已经由KubeKey或其他方式建好只想补充安装KubeSphere。这时可以创建一个空的cluster配置文件或者直接用带KubeSphere的命令重新执行一次./kk create cluster --with-kubesphere v3.3.0KubeKey会连接到已有集群自动安装KubeSphere。这种方式适合那种“之前装了纯K8s现在需求变化要加管理平台”的场景实测还是比较顺滑的。我个人的习惯是如果目的是快速搭建一整套测试环境直接一步到位如果是生产环境想要分阶段灰度验证则先装纯K8s稳定运行一段时间后再补KubeSphere。4.2 登录、改密、理解账号体系KubeSphere装完后默认的访问端口是30880。假设集群任一节点的IP是192.168.10.11浏览器访问http://192.168.10.11:30880默认账号是admin默认密码是P88w0rd。第一次登录会强制要求修改密码改成自己的强密码并保存好。需要注意的是这里说的是KubeSphere自身的账号密码不是主机密码。登录成功后你会看到一个多租户界面的控制台。KubeSphere的账号体系可以这样理解最外层是平台级的“企业空间”你可以创建多个企业空间每个企业空间下面管理多个项目。项目是Kubernetes里命名空间的一种更易用的载体。权限上分平台管理员、企业空间管理员、项目管理员、操作员、观察者等角色也可以通过自定义角色满足更细粒度的权限需求。如果你们团队规模不大先用默认的admin账号管理所有内容即可。但既然是在正式环境用我建议尽早建立“管理员账号”和“普通用户账号”分离的习惯并通过企业空间把不同业务团队隔离开。每个团队只能看见自己的项目、工作负载和日志这样既安全又清爽。4.3 控制台有什么用不是花架子进入控制台后可以先从“集群管理”页面看看集群全貌。这里能看到节点状态、CPU/内存/磁盘消耗趋势、配额使用情况、事件列表。Kubernetes原生Dashboard也有类似能力但KubeSphere把“运维视角”和“业务视角”集成在一起操作路径更舒服。具体来说我常用到的功能有工作负载可视化管理Deployment、StatefulSet、DaemonSet可以直接修改YAML、滚动升级、查看Pod日志服务管理Service和负载均衡可视化暴露方式配置管理ConfigMap、Secret设置密钥和配置项应用商店从内置商店安装常用中间件比如MySQL、Redis还能自己上架私有应用DevOps流水线基于Jenkins实现CI/CD的可视化编排监控告警查看Pod资源用量、配置告警规则样例里已经集成了Prometheus。这些功能并不是装样子它们背后就是对Kubernetes原生API的组合操作。例如在界面上创建一个Deployment实际等同于执行一次kubectl apply看一个Pod的日志等同于读取容器标准输出。只是在一个团队里不是每个人都熟悉kubectl界面能让更多同事参与部署和排障这一点在小微团队里尤其管用。5. 安装路上的典型故障和排查思路5.1 SSH阶段就卡住优先到节点上看实际安装最常见的失败点发生在KubeKey的SSH预检阶段。常见错误类似“connect to host x.x.x.x: dial tcp: no route to host”或者“permission denied”。排查顺序是确认节点IP、用户名、密码是否正确在发起安装的机器上手动ssh root目标IP确认能否连通检查目标节点的防火墙和SELinux特别是CentOS系统如果用的是密钥认证确认私钥权限是否为600如果目标节点改了hostname先确认/etc/hosts和hostnamectl set-hostname的结果一致。还有一个容易被忽略的点如果节点是多网卡机器KubeKey在检测节点IP时可能拿到的不是预期IP导致后续节点间通信失败。这个坑可以在config-sample.yaml里给每个节点的address指定确切的内网IP并且保持所有节点之间的默认路由一致。不要在装到一半时突然改成另一块网卡的地址。5.2 镜像拉取超时最烦但最可控KubeKey在安装KubeSphere时需要从容器镜像仓库拉取大量组件镜像比如Jenkins、Prometheus、Istio等。在公司网络环境差或目标机器不能直接访问镜像仓库时安装会在TaskInstallKubeSphere阶段反复失败。解决办法有几个方向适当提高超时容忍度配置或操作中的--timeout参数调大使用本地镜像仓库把所需镜像提前同步到内网仓库再在KubeSphere配置文件里通过registry字段指定内网仓库地址为容器运行时配置镜像加速器Docker的话改/etc/docker/daemon.json的registry-mirrors即可。这里要额外说一句KubeSphere组件多镜像数量几十个手动逐个拉取再推送太费劲。更好的做法是准备一台可以访问外网的机器先部署好KubeKey和Docker用一条命令把镜像缓存打包再拷贝到内网。KubeKey文档里关于离线部署的部分就是干这个的。能离线安装对生产内网环境非常友好。5.3 DNS与网络异常别忽略集群内部解析集群安装完但是工作负载一直没Ready或者Pod之间互相通信失败很多时候不是KubeKey的问题而是Calico网络或CoreDNS的问题。Calico异常时kubectl get pod -n kube-system |grep calico里会看到calico-node一直Pending或CrashLoopBackOff。常见的诱因是宿主机没有打开net.ipv4.ip_forward内核转发或者没有加载ip_vs等相关模块。解决办法是在所有节点上开启转发并确认sysctl -w net.ipv4.ip_forward1 echo net.ipv4.ip_forward1 /etc/sysctl.conf还需要确保Kubernetes的Pod网段没有和物理网络冲突这个在前面规划网络时提过。如果Pod之间跨节点通信不通优先看Calico的BGP邻居是否能建立可以进入calico-node容器内部查看bird日志。DNS问题的现象基本都是“服务名解析不了”重点检查CoreDNS Pod是否正常、kube-dns这个Service是否被其他资源误改。修复环境时尽量不要手动去动kube-system里的Service和Endpoint很多诡异问题都是乱改改出来的。5.4 快速排查手册从“现象”到“操作”我把最常见的故障归纳成一张速查表实操时可以先对照再行动。现象可能原因查看目标快速处理KubeKey SSH预检失败密码错误 / 端口不通 / SELinux阻止手动SSH、防火墙状态修正密码或端口关闭防火墙安装卡在TaskInitK8sCluster证书生成失败 / apiserver启动异常kubelet日志、etcd日志确认时间同步、重启相关Pod端口占用情况Kubectl get nodes 有NotReadyCNI网络插件未就绪calico pod状态和日志检查内核转发、IP冲突、查看Calico日志KubeSphere登录后页面空白/502KubeSphere底层组件未完全Readyks-system命名空间的Pod状态等待2~5分钟观察Pod完成Ready再刷新Pod频繁Evicted节点磁盘或内存不足kubectl describe pod、节点监控扩容worker或者清理无用的镜像和日志如果问题排查没有头绪最有效的动作是打开/var/log/kubekey/install.log搜索出现“error”“failed”“timed out”关键字的行。然后沿着报错进入对应的Pod看详细日志。很多时候一条看起来复杂的错误本质只是DNS解析失败而解决方式就是调整一下CoreDNS或hosts文件。6. 个人经验补充与后续扩展建议KubeKey这套方案我实际部署的次数不算少踩过几次坑之后最大的体会是它是那种“会做完整的预检和已有环境适配”的工具前提是你自己先把机器搞干净。时间同步、关闭swap、防火墙、hostname四项基础工作做好安装过程的成功率几乎能到九成以上。如果你只是想在本地玩一下我的建议是直接用机器数较少的配置不一定非得三台。用一台物理机加两台虚拟机或者直接三台低配云主机效果都差不多。只要把主机名、IP、SSH的信息先写好KubeKey对虚拟机、物理机、云主机没有太大区别。每台节点后面都会跑很多Pod尽量保证每台至少有4G可用内存。装完这套集群和KubeSphere之后可以试着在界面上部署一个简单的Nginx或Demo应用再让它在多个worker节点之间调度观察节点压力分布。也可以去企业空间里开通一个DevOps项目跑一遍从Git仓库提交代码到应用自动构建发布的全过程。那是整个平台真正值钱的另一个环节。回头再考虑集群容量的时候建议提前规划好存储方案。Kubernetes默认的本地存储不适合大量有状态应用KubeSphere内置支持多种存储接入。有条件的话可以在装集群之前就把存储端的秘密搭好或者让KubeSphere和已有的NFS/Ceph/云存储对接。我现在的想法是先把这套平台跑熟再把存储和监控告警完善起来这应该是后续几篇内容的核心方向。如果你在按本文操作的过程中卡在了某个环节先翻一下节点上的/var/log/kubekey/install.log再对照本文第5节的问题表排查大部分情况都能解决。装完之后别忘了在kubectl get pod -A里确认所有组件Running那是后面一切实验的基础。
