Clusternet：超详细部署与使用教程

Clusternet（Cluster Internet）是腾讯开源、CNCF Sandbox 项目的 Kubernetes 多集群管理与应用分发平台：把公有云、私有云、混合云、边缘的成千上万个 K8s 集群像访问互联网一样统一管理，并从一个托管集群的一组 API 向多个集群分发、协调应用。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Clusternet 是一个开源的 Kubernetes 附加组件（add-on），帮助你像访问互联网一样管理成千上万个 K8s 集群——无论这些集群跑在公有云、私有云、混合云还是边缘。它以可配置的方式建立网络隧道，让你像访问本地集群一样管理/访问所有集群，免去为每个集群维护不同工具的烦恼。

它还能在托管集群（parent cluster）上用一组 API 向多个集群部署和协调应用，并提供 Kubernetes 风格的 API（继续用 KubeConfig 方式访问被管集群或其上的服务）。

1.2 核心功能

• K8s 多集群管理与治理：管理 AWS/GCP/腾讯云/阿里云等公有云、本地机房、边缘、任意 Certified K8s 发行版（含 k3s）；自动发现注册 cluster-api 创建的集群；父集群也可把自己注册为子集群；动态 RBAC 访问被管集群；基于 Node Feature Discovery 的自动打标。
• 应用协调：调度框架（in-tree/out-of-tree 插件）；跨集群调度（副本调度、按权重静态划分、按容量动态划分、子组集群调度）；支持 K8s 原生对象（Deployment/StatefulSet）、CRD、Helm Chart（含 OCI Chart）；设置覆盖（Setting Overrides）与跨集群金丝雀发布；多集群服务发现（mcs-api）。
• CLI：kubectl 插件，kubectl krew install clusternet 安装，体验与 kubectl 一致；可创建/更新/观察/删除多集群资源，像本地集群一样操作任意子集群。
• client-go 集成：提供 client-go 包装器，便于二次开发集成。

版本兼容矩阵（官方 README）：

1.3 技术架构

下图是 Clusternet 官方的整体示意：父集群通过可配置的网络隧道，统一纳管分布在边缘、IDC、公有云、混合云的众多子集群，应用从父集群的一组 API 分发到所有子集群：

Clusternet 是轻量级 add-on，由四个组件组成：

• clusternet-hub（父集群）：批准集群注册请求、为每个子集群创建 namespace/SA/RBAC；作为聚合 apiserver（AA）与 WebSocket 服务端，维护来自子集群的活跃 WebSocket 长连接；提供 K8s 风格 API 把请求转发/代理到各子集群；协调多集群应用部署。
• clusternet-scheduler（父集群）：跨集群调度器。
• clusternet-controller-manager（父集群，v0.15.0+）：控制器。
• clusternet-agent（子集群）：自动把当前集群注册为父集群的子集群（ManagedCluster）；上报心跳（K8s 版本、运行平台、健康状态）；建立到父集群的 WebSocket 全双工通道。

二、环境要求

三、部署方式

下面给出三种部署方式：方式一：Helm Chart 安装（生产推荐）→ 方式二：kind 本地一键体验 → 方式三：手动清单安装。

3.1 方式一：Helm Chart 安装（生产推荐）

组件分工：clusternet-agent 部署在子集群；clusternet-hub、clusternet-scheduler、clusternet-controller-manager（v0.15.0+）部署在父集群。

步骤 1：添加 Helm 仓库

helm repo add clusternet https://clusternet.github.io/charts
helm search repo clusternet

容器镜像同时托管在 ghcr.io（https://github.com/orgs/clusternet/packages）与 Docker Hub（https://hub.docker.com/u/clusternet），按网络选最快的源。

步骤 2：父集群安装 hub + scheduler + controller-manager

# hub
helm install clusternet-hub -n clusternet-system --create-namespace clusternet/clusternet-hub

# scheduler
helm install clusternet-scheduler -n clusternet-system --create-namespace clusternet/clusternet-scheduler

# controller-manager
helm install clusternet-controller-manager -n clusternet-system --create-namespace clusternet/clusternet-controller-manager

步骤 3：创建认证 Token

父集群 kube-apiserver 若开启了 bootstrap token 认证（显式设置 --enable-bootstrap-token-auth=true）：

kubectl apply -f https://raw.githubusercontent.com/clusternet/clusternet/main/manifests/samples/cluster_bootstrap_token.yaml

若父集群不支持 bootstrap token（如 k3s，默认 --enable-bootstrap-token-auth=false），改用 ServiceAccount Token：

kubectl apply -f https://raw.githubusercontent.com/clusternet/clusternet/main/manifests/samples/cluster_serviceaccount_token.yaml

从父集群取出 token：

kubectl get secret -n clusternet-system \
  -o=jsonpath='{.items[?(@.metadata.annotations.kubernetes\.io/service-account\.name=="cluster-bootstrap-use")].data.token}' \
  | base64 -i --decode; echo
# 输出一长串字符串，记下来，下一步要用

步骤 4：子集群安装 agent

helm install clusternet-agent -n clusternet-system --create-namespace \
  --set parentURL=https://192.168.10.10:6443 \
  --set registrationToken=07401b.f395accd246ae52d \
  clusternet/clusternet-agent

parentURL 换成父集群 apiserver 地址；registrationToken 换成步骤 3 取出的 token。 注意：父集群 kube-apiserver 需配置 --aggregator-reject-forwarding-redirect=false，否则聚合 API 可能异常。

agent chart 常用参数：

3.2 方式二：kind 本地一键体验（快速上手）

前置：Helm、kubectl、kind、Docker。

# 解决 Pod "too many open files"（inotify 资源不足）
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=512
# 持久化写入 /etc/sysctl.conf

# 克隆并启动
mkdir -p $GOPATH/src/github.com/clusternet/
cd $GOPATH/src/github.com/clusternet/
git clone https://github.com/clusternet/clusternet
cd clusternet/hack
./local-running.sh

脚本会拉起 1 个 parent + 3 个 child 的 kind 集群并自动部署 Clusternet。成功后：

export KUBECONFIG="${HOME}/.kube/clusternet.config"
kubectl config get-contexts
# 应看到 child1 / child2 / child3 / parent 四个 context

kubectl get pod -n clusternet-system
# clusternet-hub / clusternet-scheduler / clusternet-controller-manager 均 Running

3.3 方式三：手动清单安装

不使用 Helm 时，可参考官方文档「Installing Clusternet Manually」（https://clusternet.io/docs/installation/），按仓库 manifests/ 目录下的 YAML 手动 apply。

3.4 验证部署成功

1. 父集群 kubectl get pod -n clusternet-system 全部 Running；
2. 子集群注册成功：

kubectl get managedclusters -n clusternet-system

3. 子集群状态变为 Healthy / Accepted（具体字段以官方教程「Checking Cluster Registration」为准）。

3.5 k3s 部署差异

在 k3s 上安装 Clusternet 时（官方文档「Installing Clusternet on k3s」）：

• k3s 默认不支持 bootstrap token 认证，必须使用 ServiceAccount Token 注册（见 3.1 步骤 3）；
• k3s 的 kubeconfig 路径与 TLS 证书位置与标准 K8s 不同，配置 parentURL 时需确保 agent 容器内能正确访问父集群 apiserver；
• 其余 Helm 安装步骤与标准 K8s 一致。

3.6 卸载

# 父集群卸载
helm uninstall clusternet-hub clusternet-scheduler clusternet-controller-manager -n clusternet-system

# 子集群卸载 agent
helm uninstall clusternet-agent -n clusternet-system

卸载前建议先导出 ManagedCluster 资源备份，避免配置丢失。

四、使用方法

4.1 基础操作：访问子集群

# 查看已注册集群
kubectl get managedclusters -n clusternet-system

# 安装 kubectl 插件
kubectl krew install clusternet

# 像操作本地集群一样访问子集群
kubectl clusternet --cluster-id <child-cluster-id> --namespace default get pod

4.2 部署应用到多集群

官方提供交互式教程（https://clusternet.io/docs/tutorials/）：

• 副本调度（replication scheduling）：把 Deployment 副本同时发到多个子集群；
• 按权重静态划分：按权重比例分配副本；
• 按容量动态划分：按集群剩余容量调度；
• 设置覆盖（Setting Overrides）：两阶段优先级覆盖策略，支持金丝雀发布与一键回滚。

Helm Chart 应用支持 OCI 标准 Registry。

应用分发示例（在父集群操作，以官方教程为准）：

# 查看已注册集群
kubectl get managedclusters -n clusternet-system

# 创建一个跨集群应用（Subscription / HelmChart 等 CRD）
# 具体 YAML 字段参考官方教程：
# https://clusternet.io/docs/tutorials/multi-cluster-apps/
kubectl apply -f app-demo.yaml

# 查看分发状态
kubectl get app -n clusternet-system

Clusternet 通过 Subscription 类 CRD 把应用下发到选定的 ManagedCluster，支持副本/权重/容量三种调度策略，字段以官方 Reference 为准。

4.3 常用 kubectl 插件命令

kubectl clusternet --help
# 创建/更新/观察/删除多集群资源
# 与任意子集群交互，体验与本地集群一致

其他访问方式（官方教程）：

• 动态 RBAC 规则访问子集群（Visiting Child Clusters with RBAC）；
• 用专用 KubeConfig 访问子集群（Dedicated KubeConfig）；
• 直接用 curl 调用聚合 API（Visiting Child Clusters with curl）；
• 在子集群本地访问运行在其上的 Service（Locally Visit Services Running in Child Clusters）；
• 基于 mcs-api 的多集群服务发现与跨集群负载均衡。

4.4 常用资源类型

4.4 二次开发（client-go）

# go.mod 引入
# require github.com/clusternet/apis latest

参考官方示例：https://github.com/clusternet/clusternet/blob/main/examples/clientgo/demo.go

4.5 适用场景

• 多朵云/多数据中心 K8s 集群统一纳管；
• 边缘计算：大量边缘 k3s 集群的统一注册与应用下发；
• 多集群应用发布：一条命令把应用灰度到 N 个集群；
• 平台型团队：为业务线提供统一的多集群自助入口；
• 混合云统一控制面：父集群在 IDC，子集群在公有云，统一入口管理。
• 应用批量升级：跨集群灰度发布 Helm Chart，回滚一键完成。
• 多环境统一治理：dev/staging/prod 不同环境的集群统一纳管。

五、常见问题排查（FAQ）

Q1：kind 本地集群 Pod 起不来，日志报 "too many open files" - 原因：宿主机 inotify 资源不足。 - 解决：sudo sysctl fs.inotify.max_user_watches=524288 && sudo sysctl fs.inotify.max_user_instances=512，并持久化到 /etc/sysctl.conf。

Q2：子集群注册不上（ManagedCluster 一直 Pending） - 原因：agent 拿不到父集群地址、token 错误，或父集群 apiserver 未配置 --aggregator-reject-forwarding-redirect=false。 - 解决：核对 parentURL 网络可达；核对 registrationToken；检查父集群聚合层配置。

Q3：k3s 作为子集群注册失败 - 原因：k3s 默认不支持 bootstrap token 认证。 - 解决：改用 ServiceAccount Token 方式注册（见 3.1 步骤 3）。

Q4：版本兼容问题 - 原因：Clusternet 与 K8s 版本有 skew 限制。 - 解决：对照本文档 1.2 兼容矩阵；v0.18.x 仅支持 K8s ≥1.30。

Q5：跨集群调度不生效 - 原因：调度策略未正确指定，或资源预测框架未配置。 - 解决：参考官方调度教程（副本/权重/容量），按对应 YAML 配置。

Q6：父集群重启后子集群连接断了 - 原因：WebSocket 长连接断开。 - 解决：agent 会自动重连；确认 agent Pod 状态正常，网络出站未被拦截。

Q7：kubectl krew install clusternet 失败 - 原因：krew 未安装或网络问题。 - 解决：先按 https://krew.sigs.k8s.io 安装 krew；或直接从 Releases 下载 kubectl-clusternet 二进制放到 PATH。

六、部署注意事项与最佳实践

1. 版本矩阵先行：部署前先对照 K8s 版本选 Clusternet 版本（v0.18.x 要求 K8s ≥1.30）。
2. apiserver 参数：父集群务必加 --aggregator-reject-forwarding-redirect=false。
3. 镜像源：国内网络优先配置 Docker Hub 镜像（设 image.registry 为空或 docker.io）。
4. 安全：registrationToken 妥善保管，等同子集群注册凭证；RBAC 按最小权限授权。
5. 网络架构：agent 主动出站连父集群，适合子集群在 NAT/内网场景；无需在父集群开放到子集群的入站。
6. 备份：定期备份父集群 clusternet-system 命名空间资源。
7. 升级：阅读官方升级指南（Clusternet Upgrade），先父集群后子集群。
8. 资源预测：动态容量调度依赖集群资源预测框架，生产环境建议先在测试集群验证预测准确性。
9. 网络隧道：Clusternet 以可配置方式建立跨集群隧道，跨地域部署时注意带宽与延迟对 WebSocket 长连接的影响。
10. 监控：对 clusternet-agent 心跳与 WebSocket 连接做监控，及时发现离线子集群。

七、参考资料

• GitHub 仓库：https://github.com/clusternet/clusternet
• 官网与文档：https://clusternet.io/docs/
• 快速开始：https://clusternet.io/docs/quick-start/
• Helm 安装：https://clusternet.io/docs/installation/
• 交互教程：https://clusternet.io/docs/tutorials/
• Helm Charts 仓库：https://github.com/clusternet/charts
• client-go 示例：https://github.com/clusternet/clusternet/tree/main/examples/clientgo
• 邮件列表：clusternet@googlegroups.com