KubeSphere 部署实战教程(All-in-One + 多节点 + 多集群纳管)

⚠️ 版本提醒:本文记录的是基于 KubeKey v1.1.1 + K8s v1.20.4 + KubeSphere v3.1.1 的实战流程,该组合已于 2021 年底脱离官方支持周期。生产环境推荐使用最新 KubeKey v3.x + K8s v1.28+ + KubeSphere v3.4.x / v4.x,新版命令与本文大体一致,部分参数(如 --with-kubernetes 取值范围、cluster-configuration.yaml 字段名)有调整,以官方文档为准。

📌 本文定位:保留原作者的命令作为"历史步骤快照",并补充每个步骤的前置条件、安全提醒和常见踩坑。

一、All-in-One 模式安装 KubeSphere

适合开发测试环境,所有组件(etcd / master / worker)跑在同一节点。

1. 环境配置

yum install -y socat conntrack ebtables ipset

这 4 个包是 K8s 网络组件依赖,任何 K8s 安装方式都必备。socat 给 kubectl port-forward 用,conntrack 给 kube-proxy 用,ebtables/ipset 给网络策略用。

2. 下载 KubeKey

# 国内环境配置(必须,否则下载速度极慢)
export KKZONE=cn
# 下载 KubeKey v1.1.1
curl -sfL https://get-kk.kubesphere.io | VERSION=v1.1.1 sh -

💡 export KKZONE=cn 必须放在 download 命令之前,它让 KubeKey 走国内镜像下载 K8s 二进制;否则会从海外拉,大概率失败。

3. 开始安装 KubeSphere

./kk create cluster --with-kubernetes v1.20.4 --with-kubesphere v3.1.1

安装成功输出示例:

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

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

🔒 安全提醒:P@88w0rd 是 KubeSphere All-in-One 安装的默认 console 密码,任何读过本文的人都能拿去登录。生产环境必须立刻修改:

# 登录后右上角头像 → User Settings → Change Password
# 或命令行重置:
kubectl patch user admin -n kubesphere-system --type merge -p '{"spec":{"password":"你的强密码"}}'

二、添加新节点

1. 使用 KubeKey 生成配置文件

./kk create config --from-cluster

2. 配置文件中添加新节点

编辑生成的 sample.yaml,在 spec.hosts 下追加,原有 master 的 name 不能随便变更:

spec:
  hosts:
  - {name: master1, address: 192.168.0.3, internalAddress: 192.168.0.3, user: root, password: Qcloud@123}
  - {name: node1,   address: 192.168.0.4, internalAddress: 192.168.0.4, user: root, password: Qcloud@123}
  - {name: node2,   address: 192.168.0.5, internalAddress: 192.168.0.5, user: root, password: Qcloud@123}
  roleGroups:
    etcd:
    - master1
    master:
    - master1
    worker:
    - node1
    - node2

⚠️ 配置文件中明文存 root 密码是高风险操作,推荐改用 SSH 密钥:

- {name: node2, address: 192.168.0.5, internalAddress: 192.168.0.5, user: root, privateKeyPath: /root/.ssh/id_rsa}

KK 会自动用密钥登录,不必每次轮转改 yaml。

3. 执行加节点

# 国内环境配置
export KKZONE=cn
./kk add nodes -f sample.yaml

4. 节点检查

kubectl get node

💡 验证清单:加节点后必须确认 3 件事:

1. kubectl get node 新节点 Ready 状态(不是 NotReady)
2. kubectl get pods -A -o wide | grep <新节点名> 有 kube-proxy / flannel / calico 等系统 pod
3. 新节点上 df -h 检查 /var/lib/containerd(或 /var/lib/docker)有足够空间

✅ 加节点前置条件检查清单

KK 加节点失败 90% 是这块没做,强烈建议执行:

三、新增的集群以成员的方式添加到已有的集群管理器中

适用于主集群统一纳管多个 K8s 集群的场景(Host-Cluster 架构)。

1. 查看主集群的 jwtSecret

kubectl -n kubesphere-system get cm kubesphere-config -o yaml | grep -v "apiVersion" | grep jwtSecret

2. 修改成员集群配置

在成员集群的 web 页面找 集群管理 → 自定义资源 CRD,搜索 cluster-configuration,修改如下:

authentication:
  jwtSecret: "主集群的 jwtSecret"  # 替换为实际值
multicluster:
  clusterRole: member

3. 获取成员集群的 kubeconfig

cat .kube/config

⚠️ 关键坑:cat .kube/config 输出里的 server: https://localhost:6443 是成员集群本地视角的地址,主集群纳管时必须把它改成成员集群的真实可达地址(如 https://192.168.0.4:6443)。否则主集群连不上。

4. 主集群添加成员集群

1. 打开主集群的 集群管理 → 添加集群
2. 把第 3 步的 kubeconfig 内容粘贴进去
3. 修改 localhost 地址为新集群地址
4. 提交后,主集群 web 控制台会自动列出成员集群节点

💡 Host vs Member 区别:clusterRole: host 是主集群(管别人),clusterRole: member 是被管理的集群。两者之间用 jwtSecret 互认,但业务 pod 跑在 member 上,host 主要做统一面板、统一告警、统一权限下发。

🐛 常见错误速查

📚 相关阅读

• KubeSphere 本地存储 PVC 的默认落盘位置(OpenEBS Local PV) — 部署后存储数据放哪了
• K8s 证书过期更新方法 — 集群跑久了必踩的坑
• 天翼云节点使用 crictl 进入容器 — 容器调试利器