Clusternet: A Cloud‑Native Multi‑Cluster Management Solution for Kubernetes

Clusternet (Cluster Internet)

is an open‑source Kubernetes multi‑cluster management cloud‑native project from Tencent that lets you manage millions of clusters as easily as accessing the Internet, regardless of whether they run on public, private, hybrid, or edge environments.

It provides a Kubernetes‑style API, allowing access to managed clusters via KubeConfig and supports deployment and coordination of applications from a host cluster to multiple child clusters, even when they are behind VPCs, firewalls, or edge networks.

1 Architecture

The architecture consists of two lightweight components: clusternet-agent (deployed in each child cluster) and clusternet-hub (deployed in the parent cluster). The agent registers the child as a ManagedCluster, reports metadata, and establishes a secure full‑duplex WebSocket tunnel to the hub.

The hub, running as an Aggregated APIServer (AA), approves registration requests, creates dedicated resources (namespace, ServiceAccount, RBAC), acts as a WebSocket server for multiple tunnels, and provides a Kubernetes‑style REST API to proxy or upgrade requests to each child cluster.

⚠️ Note: Because clusternet-hub runs as an AA, the parent apiserver must be reachable by the hub service.

2 Concepts

A managed Kubernetes cluster is called a child cluster , and the cluster it registers to is the parent cluster . The agent runs in the child, the hub in the parent. Clusternet can distribute native resources (Deployment, StatefulSet, ConfigMap, Secret), custom resources, and HelmChart applications.

Key custom resources include: ClusterRegistrationRequest: created by the agent in the parent to request registration. ManagedCluster: created by the hub after approving the registration request. HelmChart: represents a Helm chart configuration. Subscription: defines which clusters should receive which resources. Localization and Globalization: control override priority for namespace‑scoped and cluster‑scoped resources. Base: rendered with both Globalization and Localization settings to produce a Description object that is finally deployed.

3 Deployment

Deploy clusternet-agent in each child cluster and clusternet-hub in the parent cluster.

Clone the source code:

$ git clone https://github.com/clusternet/clusternet.git

Deploy the hub: $ kubectl apply -f deploy/hub Create a bootstrap token for the agent:

# Create a bootstrap token: 07401b.f395accd246ae52d
$ kubectl apply -f manifests/samples/cluster_bootstrap_token.yaml

Deploy the agent, configuring the sync mode (Push, Pull, or Dual) via --cluster-sync-mode. The recommended mode is Dual, often used with the AppPusher feature.

After the agent is deployed, create a Secret containing the registration token and the parent URL (must be HTTPS). Example:

$ kubectl create ns clusternet-system
$ PARENTURL=https://192.168.10.10 REGTOKEN=07401b.f395accd246ae52d envsubst < ./deploy/templates/clusternet_agent_secret.yaml | kubectl apply -f -

Apply the agent manifests: $ kubectl apply -f deploy/agent Check registration status with kubectl get clsrr and inspect the approved ClusterRegistrationRequest and generated RBAC rules.

The agent updates the ManagedCluster status every 3 minutes by default; this interval can be changed with --cluster-status-update-frequency.

Install the Clusternet kubectl plugin via krew: $ kubectl krew install clusternet After installation, use commands such as kubectl clusternet apply, kubectl clusternet get, and kubectl clusternet describe to manage resources.

4 Example

Deploy an example application named app‑demo using a Subscription that lists target clusters and the resources (HelmChart, Namespace, Service, Deployment) to be distributed.

# examples/applications/subscription.yaml
apiVersion: apps.clusternet.io/v1alpha1
kind: Subscription
metadata:
  name: app-demo
  namespace: default
spec:
  subscribers:
    - clusterAffinity:
        matchLabels:
          clusters.clusternet.io/cluster-id: dc91021d-2361-4f6d-a404-7c33b9e01118
  feeds:
    - apiVersion: apps.clusternet.io/v1alpha1
      kind: HelmChart
      name: mysql
      namespace: default
    - apiVersion: v1
      kind: Namespace
      name: foo
    - apiVersion: apps/v1
      kind: Service
      name: my-nginx-svc
      namespace: foo
    - apiVersion: apps/v1
      kind: Deployment
      name: my-nginx
      namespace: foo

Update the cluster ID, then apply the subscription:

$ kubectl clusternet apply -f examples/applications/

Verify the created resources with kubectl clusternet get subs -A, kubectl clusternet get chart, kubectl clusternet get ns, etc., and inspect deployment status via kubectl describe desc or directly with Helm in the child cluster.

For more details, refer to the official repository: https://github.com/clusternet/clusternet