本节介绍如何通过代理连接添加成员集群。

如果主集群无法访问成员集群的 Kubernetes API 服务，您可以设置成员集群连接到主集群对外暴露的 tower 服务从而添加成员集群。

前提条件

  • 您需要在主集群中具有 platform-admin 角色。

  • KubeSphere 企业版平台需要安装并启用 KubeSphere 多集群代理连接扩展组件。

  • 成员集群所有节点必须能访问主集群 tower 服务的外部访问地址。取决于您的网络环境，您可能需要配置防火墙和流量转发规则。

步骤 1：设置代理服务地址

在主集群安装“KubeSphere 多集群代理连接”扩展组件后，将在系统项目 kubesphere-system 中自动创建一个名为 tower 的服务，服务类型为 LoadBalancer。

集群中有可用的 LoadBalancer

在主集群节点执行以下命令。

kubectl -n kubesphere-system get svc

若主集群中有可用的 LoadBalancer，其输出结果可能如下所示。

NAME       TYPE            CLUSTER-IP      EXTERNAL-IP     PORT(S)              AGE
tower      LoadBalancer    10.233.63.191   139.198.110.23  8080:30721/TCP       16h

tower 服务有相应的 EXTERNAL-IP 地址。该地址将由 KubeSphere 自动获取并配置代理服务地址，这意味着您可以跳过设置代理服务地址这一步。

说明

主流公网云厂商一般会提供 LoadBalancer 解决方案，并且负载均衡器可以自动分配外部 IP。如果您的集群运行在本地环境中，尤其是在裸机环境中，可以使用 OpenELB 作为负载均衡器解决方案。

集群中没有可用的 LoadBalancer

  1. 在主集群节点执行以下命令。

    kubectl -n kubesphere-system get svc

    若主集群中没有可用的 LoadBalancer，其输出结果可能如下所示。在此示例中，可以看出 NodePort 为 30721。

    NAME       TYPE            CLUSTER-IP      EXTERNAL-IP     PORT(S)              AGE
tower      LoadBalancer    10.233.63.191   <none>       8080:30721/TCP       16h

  2. 由于 EXTERNAL-IP 为 none，您需要手动设置代理地址。例如，如果您主集群的公网 IP 地址为 139.198.120.120，需要配置端口转发规则，将公网 IP 的某一端口（如 30000）转发到 {NodeIP}:{NodePort}，如 172.31.17.xx:30721。

  3. 将 proxyPublishAddress 添加到 tower 保密字典中，以便访问 Tower。

    kubectl -n kubesphere-system edit secret tower

    在保密字典中，添加以下内容：

    stringData:
  configuration.yaml: |
    proxyPublishAddress: http://{主集群的公网 IP 地址}:{port}
    说明

    {port} 为您在步骤 2 中指定的公网 IP 的端口。

    完整配置示例如下：

    kind: Secret
apiVersion: v1
metadata:
  name: tower
  namespace: kubesphere-system
  creationTimestamp: '2025-06-16T02:19:11Z'
  labels:
    app.kubernetes.io/managed-by: Helm
    config.kubesphere.io/type: cluster-connection-config
    kubesphere.io/extension-ref: tower
  annotations:
    meta.helm.sh/release-name: tower
    meta.helm.sh/release-namespace: extension-tower
type: config.kubesphere.io/cluster-connection-config
stringData:   # <========  stringData
  configuration.yaml: |
    proxyPublishAddress: http://139.198.120.120:30000

    保存保密字典后，stringData 下的内容将自动转换为

    data:
  configuration.yaml: <base64 编码后的内容>
    说明

    如果在 KubeSphere 多集群代理连接 之前的版本中配置了 proxyPublishAddress，若在升级到新版本后想要修改配置，您需要按照扩展中心中该扩展组件详情页的说明，用 base64 查看之前的配置，在保密字典中添加原有配置，并添加新的 proxyPublishAddress 配置。

步骤 2：添加成员集群

  1. 以具有 platform-admin 角色的用户登录主集群的 Web 控制台。

  2. 点击集群管理。

  3. 在集群管理页面，点击添加集群。

  4. 在基本信息页签，设置成员集群的名称、标签、提供商和描述信息，然后点击下一步。

    参数 描述

    名称

    成员集群的名称。名称只能包含小写字母、数字和连字符（-），必须以小写字母或数字开头和结尾，最长 60 个字符。

    标签

    成员集群的标签。您可以在下拉列表中选择标签，也可以手动输入标签。

    提供商

    成员集群的提供商。您可以在下拉列表中选择提供商，也可以手动输入提供商。

    描述

    成员集群的描述信息。描述可包含任意字符，最长 256 个字符。

    在高级设置下，设置集群的用途标识。

  5. 在连接设置页签，将连接方式设置为 tower，点击下一步。

  6. 在集群配置页签，根据需要设置集群配置，然后点击创建。您将看到“等待集群加入”页面。

  7. 根据页面提示，在成员集群的节点上创建 agent.yaml 文件。

  8. 复制页面提供的信息到 agent.yaml 文件中，然后保存。其内容根据以上配置的代理服务地址自动生成。

  9. 在成员集群节点上，执行以下命令添加集群。

    kubectl create -f agent.yaml

    等待一段时间，成员集群添加完成后将显示在集群管理页面的集群列表中。