KubeSphere实战：利用kubekey快速部署高可用Kubernetes集群与KubeSphere平台

关注

原创最新推荐文章于 2026-02-15 01:51:34 发布 184 阅读 AI 写同款· GEO 优化 ›

KubeKey一键安装部署k8s集群和KubeSphere详细教程 KubeKey是一个开源轻量级工具，采用go语言开发，用于部署Kubernetes集群。阅读详情

1. 为什么你需要KubeSphere和kubekey？

如果你正在或者打算接触云原生，那你肯定绕不开Kubernetes。Kubernetes很强大，但实话实说，它也挺“劝退”的。光是那一堆YAML文件、各种抽象概念（Pod、Service、Ingress、PV/PVC），还有复杂的网络和存储配置，就足以让新手望而却步。我自己刚上手那会儿，光是搭建一个能用的集群就折腾了好几天，各种证书问题、网络不通、镜像拉取失败，踩坑踩到怀疑人生。

这时候，KubeSphere就出现了。你可以把它理解为一个给Kubernetes穿上的“漂亮外衣”和“智能管家”。它提供了一个非常直观的图形化控制台，把Kubernetes那些复杂的操作都封装成了点点鼠标、填填表单就能完成的事情。比如你想部署一个应用，在KubeSphere里，你不需要手写复杂的Deployment和Service YAML，通过它的“应用模板”或者“应用商店”，几步就能搞定。它还集成了很多企业级功能，比如多租户管理、监控告警（基于Prometheus）、日志查询（基于Elasticsearch）、DevOps流水线、服务网格（Istio）等等。简单说，有了KubeSphere，你和你的团队就能更专注于业务开发，而不是整天和kubectl命令较劲。

那kubekey又是干嘛的呢？它就是帮你把“搭建Kubernetes集群”和“安装KubeSphere平台”这两件麻烦事，变成“一键搞定”的神器。以前，我们要用kubeadm一步步初始化集群、安装网络插件、配置存储，然后再用Helm去部署KubeSphere，过程繁琐且容易出错。kubekey是KubeSphere官方用Go语言开发的集群生命周期管理工具，它把所有这些步骤都自动化了。你只需要准备好几台干净的Linux机器，写一个简单的配置文件，然后运行一条命令，它就能自动帮你完成从操作系统依赖检查、容器运行时安装、Kubernetes集群部署到KubeSphere平台安装的全过程。它支持高可用部署，也支持在已有的Kubernetes集群上单独安装KubeSphere，非常灵活。

所以，这套组合拳特别适合以下人群：想快速搭建云原生环境进行学习测试的开发者和学生；中小团队希望快速拥有一个功能完善、开箱即用的容器平台，而无需投入大量运维精力；以及需要频繁搭建和销毁集群的CI/CD测试场景。接下来，我就手把手带你走一遍实战流程。

2. 部署前的环境准备与规划

在按下那个“一键安装”按钮之前，充分的准备工作是成功的关键。这一步没做好，后面很可能就会卡在奇怪的错误上。根据我的经验，把环境理清楚，能省去至少80%的麻烦。

首先，我们需要准备机器。我强烈建议至少使用三台CentOS 7.9或Ubuntu 20.04 LTS的服务器（虚拟机或物理机均可）。为什么是三台？因为我们要搭建一个最小化的高可用集群。一台作为Master（控制平面），如果它挂了，整个集群就失联了，这显然不符合生产要求。使用三台，我们可以部署多Master节点，实现控制平面的高可用。这里我以三台机器为例，配置建议至少2核CPU、4GB内存、40GB磁盘。我的实验环境规划如下：

主机IP	主机名	角色
192.168.1.101	ks-master-01	主控制节点、etcd、工作节点
192.168.1.102	ks-master-02	控制节点、etcd、工作节点
192.168.1.103	ks-master-03	控制节点、etcd、工作节点

你可能注意到了，我把所有节点都同时当作控制节点和工作节点。这在资源有限的学习或测试环境中是完全可行的，kubekey也支持这种模式。在生产环境，通常会分离控制平面和工作节点。

接下来，我们需要在所有三台机器上执行一系列初始化命令。这些操作主要是为了满足Kubernetes运行的基础要求。

第一步，关闭防火墙和SELinux。 Kubernetes需要自己管理网络规则，系统防火墙可能会干扰其网络组件（如Calico、Flannel）的正常工作。执行以下命令：

# 关闭防火墙（临时生效）
systemctl stop firewalld
# 关闭防火墙（永久生效，重启后依然关闭）
systemctl disable firewalld
# 对于Ubuntu系统，通常是ufw: ufw disable

# 关闭SELinux（临时生效）
setenforce 0
# 关闭SELinux（永久生效，需要编辑配置文件后重启）
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

第二步，关闭swap交换分区。 Kubernetes的设计理念是，当Pod内存不足时，应该被杀死并重新调度，而不是使用缓慢的磁盘交换空间，这会影响性能和稳定性。

# 临时关闭当前已启用的swap
swapoff -a
# 永久关闭，注释掉/etc/fstab中所有包含swap的行
sed -ri 's/.*swap.*/#&/' /etc/fstab

第三步，配置内核参数，将桥接的IPv4流量传递到iptables链。 这是为了让Kubernetes Service的流量转发正常工作。

cat > /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
# 使配置生效
sysctl --system

第四步，确保所有节点时间同步。 集群节点间时间不一致会导致证书错误、日志时间错乱等一系列诡异问题。

# 安装时间同步工具（CentOS）
yum install -y ntpdate
# 同步时间（可以换成国内的NTP服务器，如ntp.aliyun.com）
ntpdate time.windows.com
# 更推荐配置chronyd服务进行持续同步

第五步，安装容器运行时。 Kubernetes 1.20之后，Docker不再是唯一选择，但仍然是兼容性最好的。我们安装Docker并配置国内镜像加速。

# 安装yum工具包
yum install -y yum-utils
# 添加阿里云Docker仓库
yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
# 安装指定版本的Docker（这里安装较稳定的19.03版本）
yum install -y docker-ce-19.03.15 docker-ce-cli-19.03.15 containerd.io
# 启动并设置开机自启
systemctl enable docker --now
# 配置Docker镜像加速器
mkdir -p /etc/docker
cat > /etc/docker/daemon.json << EOF
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "registry-mirrors": ["https://你的ID.mirror.aliyuncs.com", "https://docker.mirrors.ustc.edu.cn"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  }
}
EOF
# 重启Docker使配置生效
systemctl restart docker

第六步，安装Kubernetes所需的系统依赖。

yum install -y socat conntrack ebtables ipset

最后，别忘了为每台机器设置一个唯一的主机名，并配置/etc/hosts文件，让它们能通过主机名互相解析。在所有节点上编辑/etc/hosts，添加：

192.168.1.101 ks-master-01
192.168.1.102 ks-master-02
192.168.1.103 ks-master-03

做完这些，我们的基础环境就准备好了。建议每执行完一步都检查一下是否成功，比如用docker version看看Docker是否安装正确。

3. 下载kubekey并生成集群配置

环境准备好后，我们就可以请出今天的主角——kubekey了。kubekey是一个单独的二进制文件，非常轻量。我们只需要在其中一台机器上操作（通常选第一个Master节点，也就是我们规划中的ks-master-01），它就会通过SSH连接到其他节点自动完成所有部署工作。

首先，我们下载kubekey。因为网络原因，直接从GitHub下载可能会很慢甚至失败。kubekey很贴心地提供了中国区的镜像下载方式。我们登录到ks-master-01节点，执行：

# 设置下载区域为中国，这个环境变量非常重要！
export KKZONE=cn
# 使用官方脚本下载最新稳定版的kubekey（截止到我写这篇文章时是v3.0.7）
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.7 sh -

这条命令会自动下载对应系统架构的kk二进制文件。下载完成后，当前目录下会多出一个名为kk的文件。我们把它放到系统的可执行路径下，方便以后使用：

chmod +x kk
mv kk /usr/local/bin/
# 验证是否安装成功
kk version

如果看到输出版本信息，比如kubekey version v3.0.7，就说明安装成功了。

接下来，我们要创建集群的配置文件。这是整个部署过程中最关键的一步，你的集群长什么样，全由这个YAML文件定义。kubekey提供了非常方便的命令来生成配置模板：

# 创建一个包含Kubernetes v1.23.10和KubeSphere v3.3.2的配置模板
kk create config --with-kubernetes v1.23.10 --with-kubesphere v3.3.2

执行后，会在当前目录生成一个名为config-sample.yaml的文件。我们先用cat命令看一眼它的结构，然后用vim或你喜欢的编辑器打开它进行修改。

cat config-sample.yaml
vim config-sample.yaml

这个配置文件内容比较长，但我们需要修改的核心部分就几块。我挑重点说：

第一部分，spec.hosts： 这里列出了集群中的所有节点信息。你需要把模板里的示例IP和登录信息，替换成你自己机器的真实信息。

spec:
  hosts:
  - {name: ks-master-01, address: 192.168.1.101, internalAddress: 192.168.1.101, user: root, password: "YourNode101Password"}
  - {name: ks-master-02, address: 192.168.1.102, internalAddress: 192.168.1.102, user: root, password: "YourNode102Password"}
  - {name: ks-master-03, address: 192.168.1.103, internalAddress: 192.168.1.103, user: root, password: "YourNode103Password"}

name: 主机名，必须和之前设置的一致。
address: 外部可访问的IP，用于kubekey SSH连接。
internalAddress: 集群内部通信的IP，通常和address一样。
user和password: SSH登录的用户名和密码。强烈建议使用root用户，避免权限问题。如果你的机器使用密钥登录，可以配置privateKeyPath字段指定私钥路径。

第二部分，spec.roleGroups： 这里定义节点的角色。我们要搭建高可用集群，所以需要把三个节点都放入etcd、control-plane和worker组。

  roleGroups:
    etcd:
    - ks-master-01
    - ks-master-02
    - ks-master-03
    control-plane:
    - ks-master-01
    - ks-master-02
    - ks-master-03
    worker:
    - ks-master-01
    - ks-master-02
    - ks-master-03

这样配置意味着每个节点都身兼数职：既是存储集群状态的etcd成员，也是运行控制组件的控制平面，还是运行实际工作负载的工作节点。

第三部分，spec.controlPlaneEndpoint： 这是高可用集群的访问入口，也叫负载均衡器地址。在生产环境中，你需要在前端配置一个负载均衡器（如HAProxy、Nginx或云厂商的LB），将流量分发到后端的多个Master节点。在我们的实验环境中，可以暂时先用其中一个Master节点的IP和端口。注意，这个端口6443是Kubernetes API Server的默认端口。

  controlPlaneEndpoint:
    domain: lb.kubesphere.local # 域名，可自定义
    address: 192.168.1.101 # 暂时先用第一个master的IP，生产环境换成LB的IP
    port: 6443

第四部分，spec.kubernetes和spec.registry： 这里可以配置Kubernetes的版本、容器运行时类型（默认containerd，我们之前装了Docker，kubekey也能识别并适配）、网络插件（默认calico）等。一般保持默认即可。registry部分可以配置私有镜像仓库，如果从公有仓库拉取镜像慢，可以在这里配置镜像仓库镜像。

第五部分，spec.addons： 这里就是配置KubeSphere的地方！生成的模板里，KubeSphere默认是以“最小化”模式安装的，只包含核心功能。KubeSphere提供了多种可插拔的功能组件，你可以根据需要开启。

  addons:
  - name: kubesphere
    namespace: kubesphere-system
    sources:
      chart:
        name: kubesphere
        repo: https://charts.kubesphere.io/main
        valuesFile: /home/root/values.yaml # 这是一个指向自定义values文件的路径
    enabled: true
    overrideValues:
      common:
        etcd:
          monitoring: false
          endpointIps: 192.168.1.101,192.168.1.102,192.168.1.103 # 手动指定etcd节点IP
      alerting:
        enabled: false
      auditing:
        enabled: false
      devops:
        enabled: false
        jenkinsMemoryLim: 2Gi
      events:
        enabled: false
      logging:
        enabled: false
      metrics_server:
        enabled: false
      monitoring:
        storageClass: ""
      multicluster:
        clusterRole: none
      network:
        networkpolicy:
          enabled: false
        topology:
          type: none
      openpitrix:
        enabled: false
      servicemesh:
        enabled: false

如果你想体验KubeSphere完整的DevOps能力（CI/CD流水线）或服务网格（Istio），可以把devops.enabled或servicemesh.enabled改为true。不过要注意，开启这些组件会消耗更多的CPU和内存资源。第一次安装，我建议先保持最小化，成功进入控制台后再按需启用。

配置文件修改完成后，务必仔细检查几遍，尤其是IP地址、密码和角色分组，一个字符的错误都可能导致安装失败。

4. 一键启动安装与监控部署过程

最激动人心的时刻到了！前面所有的准备，都是为了这一刻的一条命令。在ks-master-01上，确保你还在存放config-sample.yaml文件的目录下，然后执行：

# 再次确保使用中国区，加速镜像拉取
export KKZONE=cn
# 开始创建集群，-f 指定配置文件，并用tee命令将日志同时输出到屏幕和文件
kk create cluster -f config-sample.yaml | tee kk-install.log

按下回车后，kubekey就正式开工了。屏幕上会开始滚动大量的日志信息，不要慌，这是它在按部就班地执行任务。整个过程完全是自动化的，主要包括以下几个阶段，你可以通过日志关键字来判断进度：

环境预检： kubekey会SSH连接到所有配置的节点，检查操作系统版本、内核参数、端口占用、依赖包、Docker版本等是否满足要求。如果这里报错，一定要根据提示解决，比如某个端口被占用，或者swap没关干净。
安装二进制文件： 在所有节点上安装kubeadm, kubelet, kubectl以及网络插件、存储插件等所需的二进制文件。
初始化集群： 在第一个控制节点（ks-master-01）上使用kubeadm初始化Kubernetes集群，并生成加入集群所需的令牌和证书。
加入控制节点： 将其他控制节点（ks-master-02, ks-master-03）加入到集群中，形成高可用的控制平面。
加入工作节点： 将所有工作节点加入到集群。
安装网络插件： 部署Calico（默认）或你指定的其他CNI插件，为Pod提供网络通信能力。
安装存储插件： 部署默认的存储类（通常是OpenEBS或NFS Provisioner），用于动态提供持久化存储。
安装KubeSphere： 这是最后也是最长的一个阶段。kubekey会使用Helm将KubeSphere的各种组件部署到kubesphere-system等命名空间下。你会看到很多Pod在创建、初始化。

整个过程视网络速度和机器性能，大概需要10到30分钟。期间可能会长时间停留在“Downloading images”或“Waiting for pod ready”，这是正常的，它在拉取大量的Docker镜像。一定要保持网络畅通，耐心等待。

一个非常重要的技巧：不要断开SSH连接！ 如果因为网络波动导致连接断开，安装进程可能会中断。你可以使用screen或tmux工具来运行安装命令，这样即使终端断开，进程也会在后台继续执行。安装完成后，你会在日志的最后看到类似这样的成功信息：

#####################################################
###              Welcome to KubeSphere!           ###
#####################################################

Console: http://192.168.1.101:30880
Account: admin
Password: P@88w0rd

NOTES：
  1. After logging into the console, please check the
     monitoring status of service components in
     "Cluster Management". If any service is not
     ready, please wait patiently until all components
     are up and running.
  2. Please modify the default password after login.

恭喜！这表示你的高可用Kubernetes集群和KubeSphere平台已经部署成功了。日志里给出了控制台的访问地址、用户名和初始密码。请务必把这些信息保存好。

5. 登录验证与基础功能探索

现在，打开你的浏览器，输入http://192.168.1.101:30880（IP换成你的第一个Master节点IP）。你会看到KubeSphere的登录页面。用日志中提供的admin账号和密码登录。

第一次登录，系统会强制要求你修改一个高强度的密码，按照提示操作即可。修改成功后，你就正式进入了KubeSphere的炫丽控制台了！

首先，我建议你点开左上角的“平台管理”，进入“集群管理”。在这里，你可以看到我们刚刚搭建的集群（通常叫default）。点击集群名称，进入集群详情页。在“节点”标签下，你应该能看到ks-master-01、ks-master-02、ks-master-03三个节点，并且状态都是“运行中”。这证明我们的三节点高可用集群已经健康运行。

然后，你可以到“应用负载”下的“工作负载”里看看。这里会列出所有系统运行所需的Deployment和StatefulSet，比如KubeSphere自己的前端、后端、各种Operator等。刚开始可能有些Pod还在创建中，状态是“容器创建中”或“调度中”，稍等几分钟刷新一下，它们都会变成“运行中”。

接下来，我们体验一下KubeSphere最吸引人的功能之一：一键部署应用。我们不去写YAML文件。点击“应用”，选择“应用模板”。KubeSphere内置了一个应用商店，里面有很多预配置好的常见应用。我们找一个简单的来试试，比如部署一个nginx。

在应用模板页面，点击“创建”。
在弹出的对话框中，选择“来自应用模板”。
在搜索框输入nginx，你会看到来自Bitnami等仓库的Nginx Chart。
点击一个Nginx模板，进入部署页面。这里你可以修改应用名称（比如my-nginx）、选择部署的集群和项目（命名空间）。
大部分配置都可以保持默认，直接滚动到最下面，点击“部署”。
部署完成后，你可以在“应用”列表里找到my-nginx。点击进入详情，可以看到它创建了一个Deployment和一个Service。
为了让外部能访问，我们需要创建一个“网关”（Ingress Controller）。KubeSphere默认已经安装了基于Nginx的Ingress Controller。在应用详情页，点击“服务”，找到对应的Service，点击“更多操作”，选择“编辑外部访问”。
将访问模式改为NodePort或Ingress。如果选NodePort，系统会自动分配一个端口（如30080），你就可以通过http://<节点IP>:30080访问Nginx欢迎页了。如果选Ingress，你需要配置一个域名规则。

通过这个简单的流程，你应该能感受到KubeSphere带来的便捷。它把Kubernetes资源对象的概念，封装成了更贴近运维和开发视角的“应用”、“服务”、“网关”，大大降低了操作门槛。

6. 集群的日常运维与扩缩容技巧

集群搭起来只是第一步，后续的运维管理才是重头戏。kubekey不仅在安装时给力，在日常运维中也提供了非常方便的命令。

首先，如何查看安装日志或排查问题？ 如果在安装KubeSphere时某个组件一直不健康，我们可以查看安装器的详细日志：

kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-installer -o jsonpath='{.items[0].metadata.name}') -f

这条命令会实时跟踪ks-installer这个Pod的日志，里面会详细记录每个KubeSphere组件的安装状态和错误信息，是排障的利器。

其次，如何给集群添加新的工作节点？ 业务增长了，需要扩容。首先，你需要准备一台新的、已经完成“环境准备”部分所有步骤的干净机器。然后，编辑之前的config-sample.yaml文件，在spec.hosts部分添加新节点的信息，并在spec.roleGroups.worker列表中加入新节点的名字。保存文件后，执行：

kk add nodes -f config-sample.yaml

kubekey就会自动将新节点加入到集群中，并安装所有必要的组件。非常优雅。

那么，如何安全地移除一个节点呢？ 比如某个节点硬件故障需要下线。首先，确保该节点上运行的所有Pod已经被驱逐到其他节点（Kubernetes会自动处理）。然后执行：

kk delete node <节点主机名> -f config-sample.yaml

kubekey会安全地将该节点从集群中移除。

集群升级怎么办？ Kubernetes和KubeSphere的版本迭代很快，安全补丁和新功能都需要升级。kubekey支持一键升级。但升级前务必在测试环境验证，并备份重要数据！ 升级命令类似这样：

# 升级到指定的Kubernetes和KubeSphere版本
kk upgrade --with-kubernetes v1.24.6 --with-kubesphere v3.3.2 -f config-sample.yaml

升级过程是滚动进行的，会尽量保证业务不中断，但依然存在风险，请谨慎操作。

最后，如果我想推倒重来怎么办？ 对于测试环境，我们经常需要销毁集群。kubekey提供了完整的集群删除功能：

kk delete cluster -f config-sample.yaml

这条命令会清理所有节点上的Kubernetes和KubeSphere组件，但不会删除你通过持久卷存储的数据，也不会卸载Docker。执行前请三思。

关于KubeSphere本身的功能开启，比如你想启用DevOps功能。不需要重新安装。登录控制台后，进入“集群管理”，点击“CRD”，搜索ClusterConfiguration，找到ks-installer对应的那个，点击进入详情，选择“编辑YAML”。在spec部分找到devops.enabled，将其改为true，保存。系统会自动开始安装Jenkins、SonarQube等DevOps组件，你可以在“组件管理”中查看安装进度。

7. 避坑指南与常见问题处理

踩坑是学习技术的必经之路。这里我分享几个在部署和使用过程中最容易遇到的问题和解决办法，希望能帮你节省大量时间。

坑一：镜像拉取失败或超时。 这是最常见的问题，表现为Pod状态一直是ImagePullBackOff或ErrImagePull。根本原因是网络问题，无法从k8s.gcr.io、docker.io等国外仓库拉取镜像。

解决办法： 这正是我们在安装前设置export KKZONE=cn的原因，kubekey会自动使用国内的镜像仓库镜像。如果安装后某些特定镜像还是拉取失败，可以考虑在节点上配置Docker的镜像加速器，或者使用docker pull命令手动从阿里云等国内仓库拉取镜像，然后重新打标签。例如：docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.6。

坑二：节点NotReady。 安装完成后，在KubeSphere控制台或执行kubectl get nodes发现节点状态不是Ready。

排查思路：
1. 检查网络插件Pod是否运行正常：kubectl get pods -n kube-system | grep calico（或flannel）。
2. 检查kubelet服务是否正常运行：在问题节点上执行systemctl status kubelet。如果报错，查看日志journalctl -xeu kubelet。常见原因是证书问题、cgroup驱动不一致（我们之前在Docker配置中设置了systemd就是为了避免这个）或者二进制文件路径错误。
3. 检查节点内存或磁盘压力是否过大：kubectl describe node <节点名>，看Conditions部分是否有MemoryPressure或DiskPressure。

坑三：KubeSphere控制台无法访问（30880端口不通）。

排查思路：
1. 首先确认ks-console这个Pod是否运行正常：kubectl get pods -n kubesphere-system | grep console。
2. 检查对应的Service和Ingress资源：kubectl get svc,ing -n kubesphere-system。
3. 检查节点防火墙是否关闭（我们第一步就做了）。有时云服务商的安全组规则也会拦截30880端口，需要去云控制台放行该端口。
4. 如果使用的是NodePort方式，确认你访问的IP和端口是否正确。可以用kubectl get svc ks-console -n kubesphere-system查看分配的NodePort是多少。

坑四：存储配置问题，Pod提示“Pending”，原因是“waiting for a volume to be created”。

解决办法： 这通常是动态存储供给（StorageClass）没有配置或配置不正确。安装后，执行kubectl get storageclass，看是否有默认的StorageClass且状态是Default。如果没有，你需要根据你的环境（本地、NFS、云盘）部署对应的存储插件。KubeSphere文档提供了多种存储方案的安装指南。

坑五：忘记KubeSphere的admin密码。

解决办法： 可以通过命令行重置。首先，确保你能用kubectl访问集群。然后执行以下命令：

kubectl -n kubesphere-system get secret ks-admin -o jsonpath='{.data.password}' | base64 -d

这会解密并打印出初始的admin密码。如果初始密码也被修改了，你可以通过修改Kubernetes Secret来重置：

# 设置一个新密码，比如`NewP@ssw0rd`
kubectl -n kubesphere-system patch secret ks-admin --type='json' -p='[{"op": "replace", "path": "/data/password", "value": "$(echo -n 'NewP@ssw0rd' | base64)"}]'

记住，遇到问题多查日志（kubectl logs和kubectl describe是你最好的朋友），善用KubeSphere控制台提供的可视化监控和事件查看功能，大部分问题都能定位到根源。