📚 课程目录第1章部署多集群管理工具

1. 部署多集群管理工具

任务说明

在本地环境部署一个多集群管理工具，用于统一管理多个 Kubernetes 集群。本案例选择 KubeSphere 作为管理平面，通过其多集群管理功能接入至少两个目标集群（一个作为管理集群，一个作为成员集群），实现从单一控制台查看和操作多个集群。

环境准备

Linux 主机（本文以 Ubuntu 22.04 为例），建议 4 核 8G 以上
已安装 Docker（20.10+）和 Helm（3.5+）
两个可用的 Kubernetes 集群（版本 1.20～1.26），可通过 kubeconfig 访问
集群间网络互通（管理集群需能访问成员集群的 API Server）

部署 KubeSphere 管理集群

在第一个集群（作为管理集群）上执行以下命令安装 KubeSphere 最小化实例（仅启用多集群管理组件）：

# 创建命名空间并安装 KubeSphere
kubectl create namespace kubesphere-system
kubectl create namespace kubesphere-monitoring-system

# 使用 Helm 安装 KubeSphere 核心组件
helm repo add kubesphere https://kubesphere.github.io/kubesphere/
helm repo update
helm install ks-core kubesphere/ks-core --namespace kubesphere-system --set multcluster.enabled=true --set console.enableNodePort=true

等待 Pod 就绪：

kubectl get pods -n kubesphere-system -w
# 等待所有 Pod 处于 Running 状态后，获取控制台访问地址
kubectl get svc -n kubesphere-system ks-console -o jsonpath='{.spec.ports[0].nodePort}'
# 默认账号：admin / 初始密码：P@88w0rd（首次登录后需修改）

接入成员集群

在管理集群上生成成员集群的接入令牌，然后在第二个集群（成员集群）上执行导入操作：

# 1. 在管理集群上获取集群令牌（登录 KubeSphere Web 控制台后执行）
# 路径：平台管理 → 集群管理 → 添加集群 → 选择"集群连接"方式
# 复制生成的导入命令（包含 agent 部署 YAML）

# 2. 在成员集群上执行导入命令（示例，实际以控制台生成的命令为准）
kubectl apply -f - <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: kubesphere-system
---
apiVersion: v1
kind: Secret
metadata:
  name: kubesphere-agent-secret
  namespace: kubesphere-system
type: Opaque
stringData:
  : "<从管理集群获取的>"
EOF

# 3. 部署 agent 组件（实际命令由管理集群控制台动态生成）
kubectl apply -f https://raw.githubusercontent.com/kubesphere/ks-core/master/config/agent.yaml

在管理集群控制台的集群管理页面中，等待成员集群状态变为 Ready，即完成接入。

验证方法

访问 KubeSphere 控制台（http://<管理集群节点IP>:<NodePort>），使用 admin 账号登录
进入 平台管理 → 集群管理，应能看到两个集群条目，状态均为 Ready
点击成员集群名称，进入该集群的 工作负载 页面，查看任意命名空间下的 Pod 列表，确认数据已从成员集群同步
在成员集群上创建一个测试命名空间（如 kubectl create ns test-from-console），回到 KubeSphere 控制台刷新，确认新命名空间可见

通过条件：上述 4 项检查全部通过，即证明多集群管理工具部署成功且具备跨集群管理能力。

常见问题

成员集群状态一直为 "Join 中"：检查管理集群与成员集群之间的网络连通性（telnet <成员集群APIServer地址> 6443），并确认 agent Pod 日志无报错
控制台无法访问：确认 NodePort 已暴露，且防火墙放行对应端口
版本不兼容：KubeSphere 3.4+ 要求 Kubernetes 1.20～1.26，超出范围需先升级集群