Clusterpedia: one API for searching resources across many Kubernetes clusters

An encyclopedia analogy, and what it means for the API

The name is explained in the readme and the analogy does real work. Clusterpedia is inspired by Wikipedia, and it is an encyclopedia of multi-cluster to synchronize, search for, and simply control multi-cluster resources. The Wikipedia framing explains the architecture better than the feature list does. Wikipedia is a single index that holds a copy of information whose authoritative versions live elsewhere, and it lets you read the entries and also edit them, and the readme draws the parallel exactly: the capability of Clusterpedia is not only to search for and view but also simply control resources in the future, just like Wikipedia that supports for editing entries. The word in the future is doing the work in that sentence, because it is a statement of direction rather than a shipped feature. In practice the shipped system synchronises resources from many clusters and serves them over one API, and the editing half of the Wikipedia analogy is the part to be sceptical about. The project is a Cloud Native Computing Foundation sandbox project, and the ecosystem page describes it as the Encyclopedia of Kubernetes clusters.

The aggregated API makes kubectl work across a fleet

The trick that makes the tool usable without new client code is the Kubernetes aggregated API. Based on that model, the entry portal for multi-cluster retrieval is the same as that of the master cluster, meaning the same IP and port. That is a much better user experience than a separate client library, because every tool that speaks the Kubernetes API, kubectl included, works against the fleet without modification. The readme gives a concrete example of the raw API call:

$ kubectl get --raw "/apis/clusterpedia.io/v1beta1/resources/apis/apps" | jq

The response is an APIGroup listing the versions available for the apps group, with a preferred version. The group is registered under the clusterpedia.io API group, and the version segment is what selects the retrieval path. Behind that is the compatibility with the Kubernetes OpenAPI, which the documentation credits for the more powerful search features, and the practical result is that you can retrieve resources using kubectl, client-go or controller-runtime client. The metadata can also be retrieved through the client-go metadata interface, which is the cheap path when you only need names and labels rather than full objects. The upstream project publishes a client-go example showing how to list Clusterpedia resources.

One resource version across clusters running different Kubernetes releases

The version story is the problem this solves most concretely. Clusterpedia supports importing Kubernetes 1.10 and later, and it performs automatic conversion of different versions of Kubernetes resources, so you can retrieve resources with the same version even when the clusters behind them run different releases. The readme's example makes the point concretely: the version of deployments is v1beta1 in Kubernetes 1.10 and it is v1 in Kubernetes 1.24, and yet the API reports the group with v1, v1beta2 and v1beta1 all available and v1 preferred. The example output shows an APIGroup whose versions list includes apps/v1, apps/v1beta2 and apps/v1beta1, with apps/v1 as the preferred version. This is the kind of thing that gets ugly fast in a fleet, because a dashboard written against one API version breaks the first time it meets a cluster that has not been upgraded yet, and the answer of keeping one client per cluster version is the thing multi-cluster tooling is supposed to remove.

Collection resources and the search conditions

The retrieval features are the second half of the story, and there are two of them. The first is a single API for different types of resources, using the Collection Resource concept to retrieve Deployments, DaemonSets and StatefulSets together, and the readme shows the collection listing:

$ kubectl get collectionresources

The output defines named collections, with one called any that matches everything, one called workloads covering deployments, daemonsets and statefulsets, and one called kuberesources that matches a long list of API groups including admission, apiextensions, apps, authentication, authorization, autoscaling, batch, certificates, coordination, discovery, events, extensions, flowcontrol, imagepolicy, internal apiserver, networking, node, policy, rbac, scheduling and storage. The second half is rich retrieval conditions, with filtering by cluster, namespace, name and creation time, searching by parent or ancestor owner, a multi-cluster label selector, an enhanced field selector, and custom search conditions. The ancestor owner search is the interesting one for multi-cluster work, because it answers the question of what does this object belong to across a fleet, which is the question a per-cluster kubeconfig cannot answer at all.

Synchronisation policies that adapt to your CRDs

The synchronisation side is where the platform integration happens, and it is deliberately configurable rather than fixed. Wildcards can sync all types of resources within a specified group or cluster, and there is support for synchronising all custom resources. The type and version of resources that Clusterpedia synchronises can be adapted to your CRD and API aggregation changes, which is the part that makes it usable with a platform that ships its own resources. The deployment model is that Clusterpedia can be deployed as a standalone platform or integrated with Cluster API, Karmada, Clusternet, vCluster, KubeVela and other multi-cloud platforms, and the readme makes the point that users do not need to maintain Clusterpedia manually because it can work as one of the internal components of those platforms. The repository ships the policy objects as examples, with a cluster import policy, a cluster sync resources file, a synchronisation RBAC file and a sample cluster definition, which are the four things you need to define to bring a new cluster into the encyclopedia.

Low memory, storage independence and the components you deploy

The operational claims are about efficiency and independence. The readme lists very low memory usage and weak network optimisation, with the mechanism being optimised caches used by the informer so the memory usage is very low for resource synchronisation, and automatic start and stop of synchronisation based on cluster health status. High availability is listed as a feature without further detail in what is available here, and there is no dependency on specific storage components, though the sentence on that is cut off in the source, so the details of what it does depend on are not visible. What the go.mod and the Makefile do tell you is the shape of the system, because the workspace builds four binaries: an apiserver, a binding apiserver, a clustersynchro manager and a controller manager, and there is a separate builder image plus an image target per binary, published under the ghcr.io registry for amd64 and arm64. The dependencies are the standard Kubernetes stack, with the k8s.io libraries at version 0.32.13, the apiserver and apiextensions machinery, controller-runtime, and a GORM based storage layer with drivers for MySQL, PostgreSQL and SQLite, which is the answer to the storage question, plus Prometheus and OpenTelemetry for metrics and tracing.

Editorial conclusion

Clusterpedia is a good fit for a platform team that already runs several clusters across clouds and wants one query surface over them, and for anyone who has tried to make a dashboard across clusters by looping over kubeconfigs. It is the wrong tool for a single cluster, where the native API server already does the job, and it is the wrong choice if you cannot accept a component that stores a copy of your cluster state in its own database. It is also the wrong choice if you need the write side, because the documentation is careful to say the capability is to search for and view resources, with control of resources described as something to come. Before deploying it, read the storage section, because the point of no dependency on a specific storage component is accompanied by a list of what it does care about, and check the version story, since the release tags carry a Kubernetes version suffix and the project tracks a specific k8s.io dependency set. The project is Apache-2.0 licensed, the last push was on 2026-10-22, and the most recent release is v0.9.1 from 2026-04-16.

Frequently asked questions

Official sources

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