Clusternet Multi-Cluster Kubernetes Management and Setup

The Multi-Cluster Problem Clusternet Addresses

Clusternet targets organizations whose Kubernetes footprints span cloud providers, private data centers, and edge sites. Its documentation describes a common operational problem: each cluster can expose its own control plane and management conventions, forcing operators to switch credentials, endpoints, and tools. Clusternet places a hosting cluster at the center of that arrangement and presents managed clusters as resources that can be accessed through Kubernetes-style interfaces.

The project is intended for platform engineers, Kubernetes administrators, and organizations that coordinate applications across clusters rather than operating only one cluster. According to the README, Clusternet can register clusters from public and private clouds, certified Kubernetes distributions such as k3s, and edge environments. It can also discover clusters created through Cluster API, apply labels through Node Feature Discovery, and register the parent cluster as a child so that it can host workloads through the same model.

This is more than a saved list of kubeconfig files. The stated scope includes cluster governance, dynamic RBAC for visiting managed clusters, scheduling applications across multiple destinations, representing Helm and CRD resources, and multi-cluster service discovery through mcs-api. That broader scope makes Clusternet relevant when application placement and central administration must work together. A team with one isolated development cluster will probably gain little from the added control-plane components and networking model.

Hub, Agent, Scheduler, and Controller Data Flow

The repository README identifies four components: `clusternet-hub`, `clusternet-agent`, `clusternet-scheduler`, and `clusternet-controller-manager`. Based on that layout, Clusternet separates the central management plane from the software that participates in managed clusters. The hosting cluster accepts cluster registrations and multi-cluster resource definitions, while the remaining components support communication, placement decisions, and reconciliation.

The documented network mechanism is configurable tunneling. The README says Clusternet sets up network tunnels so that managed clusters can behave as if they were local. Its Kubernetes-styled API also allows access to a selected managed cluster or service using familiar Kubernetes mechanisms such as KubeConfig. This design matters because direct, separately administered control planes create credential and endpoint fragmentation. A central registration and access layer reduces that fragmentation, although it also introduces connectivity and authorization paths that operators must understand.

Application placement is handled through a scheduling framework with in-tree and out-of-tree plugins. The README lists replication scheduling, weight-based static division, capacity-based dynamic division, subgroup scheduling, and extensible resource predictor topologies. It also documents native Kubernetes objects, CRDs, Helm charts, and OCI-based Helm charts as supported resource types. Overrides use a two-stage priority model, and the documentation says they support rollback and cross-cluster canary rollout.

The control path is therefore broader than simple resource forwarding. A submitted resource passes through Clusternet APIs, scheduling or interpretation, and reconciliation toward selected clusters. The README does not document the complete wire protocol, retry behavior, or failure semantics for every controller, so those details should be checked in version-specific documentation before relying on a particular workflow.

Installing the Clusternet kubectl Plugin

The clearest installation command documented in the README installs Clusternet as a kubectl plugin through Krew. This gives operators a command surface intended to feel consistent with kubectl for creating, updating, watching, and deleting multi-cluster resources, as well as interacting with child clusters.

Run this on the machine where kubectl is already configured:

kubectl krew install clusternet

The expected result is Krew adding the Clusternet plugin to kubectl's installed extensions. The README does not provide a standalone binary installation command, so it would be unsafe to substitute another package name or download URL without consulting the linked project documentation.

For the first real deployment, the README directs users to the quick start tutorial, which describes setting up Clusternet locally with kind and deploying applications to multiple clusters. It does not reproduce the required cluster creation commands, manifest URLs, ports, credentials, or controller installation flags. Those exact steps therefore remain in the linked quick start rather than being guessed here. A reader following this article should install the plugin first, open the version-matched quick start, and confirm that kind or the intended production Kubernetes clusters satisfy its prerequisites.

Go clients have a separate integration route. The repository provides a client-go wrapper under `examples/clientgo/` and directs integrators to `examples/clientgo/demo.go`. Developers importing Clusternet APIs and CRDs are told to add `github.com/clusternet/apis` to `go.mod`. The README does not document a complete module version for that dependency.

Release and Kubernetes Compatibility Boundaries

The compatibility table deserves more attention than a simple pass mark suggests. It states that Clusternet `v0.18.x` supports Kubernetes `>=v1.30`, rejects `>=v1.28,<v1.30`, and rejects `<v1.28`. For `v0.17.x`, the listed supported range is `>=v1.28,<v1.30`, while `<v1.28` is rejected. The table also lists `v0.16.x` as compatible with all three displayed ranges.

The release information includes `v1.0.0`, dated 2026-06-28, but the README table does not identify the supported Kubernetes range for `v1.0.0`. That omission is material. An operator should not infer that the table's `v0.18.x` row applies automatically to `v1.0.0`. Version numbering, Kubernetes dependency declarations, and cluster compatibility are separate concerns until the documentation explicitly connects them.

The repository's `go.mod` declares Go `1.23.0` and Kubernetes packages at `v0.32.4`. That provides useful build context, but client-library versions do not by themselves prove which server versions every Clusternet release supports. Similarly, the Dockerfile defaults to `alpine:3.18.4`, Go `1.21.3`, and builds `clusternet-hub`, while the Makefile overrides its defaults to `alpine:3.21.0` and Go `1.23.8`. These defaults affect source builds, but users of released images should still identify the image version and documentation associated with that release.

Where Clusternet Adds Operational Cost

The main cost is architectural rather than the Go build itself. Installing Clusternet means operating a hub, agents, a scheduler, and a controller manager, then configuring tunnels between the hosting environment and member clusters. Connectivity failures, certificate handling, RBAC, controller health, and version skew all become part of the management surface. Clusternet reduces tool fragmentation, but it does not remove the need to operate distributed infrastructure.

Another limitation is documentation depth. The README confirms feature availability, but it does not publish a complete disaster recovery procedure, tunnel troubleshooting matrix, backup and restore runbook, or upgrade sequence for the four components. It also does not specify what should happen when a member cluster becomes unreachable after an application has been scheduled there. These omissions do not prove that the project lacks such procedures elsewhere, but the README itself is not enough to establish them.

Clusternet is also the wrong tool when the goal is merely to store several kubeconfig files or run a command against one remote cluster. A direct kubeconfig workflow is simpler and has fewer moving control-plane parts. Likewise, teams that do not need coordinated placement, overrides, multi-cluster services, and central governance may pay for unnecessary complexity.

Cluster API integration is valuable, but it does not make non-Cluster-API environments obsolete. Teams still need to determine how clusters are registered, how child-cluster access is authorized, and how workloads behave during disconnection. Those operational questions should be settled before standardizing on the project.

Clusternet Compared with Direct Kubeconfig Federation

A real alternative is direct multi-cluster administration through separate kubeconfig contexts. In that model, each cluster keeps its own API endpoint and credentials, while an operator changes the current context before using standard kubectl commands. The difference in approach is control-plane mediation: direct federation leaves every cluster as an independent administrative endpoint, whereas Clusternet introduces a hosting cluster, agents, tunnels, custom APIs, and scheduling controllers.

Direct kubeconfig access is easier to understand and can fit a small, stable set of clusters. It also keeps failure domains visible because the operator connects directly to each control plane. Clusternet becomes more relevant when the number of clusters makes separate credentials and endpoints difficult to manage, or when application placement must consider several clusters through shared APIs. Its multi-cluster resources, override mechanism, service discovery, and kubectl plugin are not consequences of merely saving multiple contexts.

The trade-off is that Clusternet offers more centralized coordination but requires its own operational correctness. Remote access depends on tunnels, and workload coordination depends on controllers and schedulers outside the ordinary single-cluster control loop. Cluster API can automate cluster creation, but it does not replace the need to decide how those clusters join the Clusternet management path.

Clusternet is licensed under Apache-2.0. The repository includes a top-level `LICENSE` and a `LICENSES/` directory, while the README links to the Apache License 2.0. Users still need to review applicable notices and dependencies for their own compliance process; this article does not provide legal advice.

Maintenance Signals and Upgrade Surface

The repository is not archived, and its last push was on 2026-09-25. The listed `v1.0.0` release followed the August 2025 patch releases. These facts show recent repository and release activity, but they do not by themselves define the compatibility or upgrade path for a deployment.

An upgrade can affect more than one Go module. The project depends on Kubernetes libraries, Cluster API, Helm, mcs-api, controller-runtime, and several controller-related packages in `go.mod`. At runtime, changes can involve the hub, agent, scheduler, controller manager, CRDs, RBAC, tunnel configuration, and the host cluster. The README does not document whether components can be upgraded independently, whether CRDs require manual migration, or what rollback is expected after a release change.

The Makefile provides development targets such as `make test`, `make crds`, `make verify`, `make fmt`, `make lint`, `make tidy`, and `make generated`. These are source-maintenance workflows, not a deployment tutorial. The `test` target runs the Go test suite with race detection and coverage output after generating assets, while `generated` updates CRDs and generated code. Contributors should not mistake those commands for production upgrade instructions.

For an adopter, the first upgrade check should be the release documentation for the exact Clusternet version, followed by its stated Kubernetes range and CRD changes. Because the README's compatibility table does not cover `v1.0.0`, that check cannot be deferred to the table.

Editorial conclusion

Clusternet fits platform teams that already operate Kubernetes and need a centralized control plane for heterogeneous clusters. It is a poor fit for a single local cluster or operators unwilling to manage four control-plane components and cross-cluster networking. Verify first that the selected Clusternet release supports your Kubernetes versions, that every member cluster can maintain the required tunnel, and that the intended scheduling and RBAC model matches your policies.

Frequently asked questions

Official sources

1. clusternet/clusternet on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases