# KubeAdmiral: Kubernetes federation that keeps the native API > KubeAdmiral is a multi-cluster management system grown from Kubernetes Federation v2 that drops the federated custom types in favour of native Kubernetes resources, and adds a new scheduling framework, override policies and follower scheduling. The catch is a Kubernetes version ceiling of 1.24 and a single release tag from 2024. **kubewharf/kubeadmiral** — Multi-Cluster Kubernetes Orchestration - Repository: https://github.com/kubewharf/kubeadmiral - Website: https://kubeadmiral.io - Stars: 931 · Forks: 99 - Language: Go - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/kubewharf-kubeadmiral ## Federation v2 rebuilt around native Kubernetes objects KubeAdmiral is a multi-cluster management system for Kubernetes, developed from Kubernetes Federation v2. The original project let you manage resources across clusters through federated types such as FederatedDeployment, FederatedReplicaSet and FederatedSecret, which meant learning a parallel object model before you could place a workload. KubeAdmiral's central change is to extend the Federation v2 API while keeping compatibility with the Kubernetes native API. You write the resources you already know, and the control plane handles propagation across member clusters. The new features listed in the README are specific rather than cosmetic: a new scheduling framework with a rich set of scheduling plugins, override policies, automatic propagation of dependencies with follower scheduling, status aggregation of member cluster resources, and work described as scalability, stability and user experience enhancements. The scale of the problem is the reason this exists. Running the same application across a dozen clusters by hand means maintaining the same Deployment, Service and Secret in each one, and every change is repeated. The value of a federation layer is the removal of that repetition, and the design question is always what you give up in exchange, which here is the federated type system that Federation v2 originally required. ## Override policies and follower scheduling carry the new logic Two mechanisms do most of the interesting work. Override policies are the answer to the question every multi-cluster operator asks first: how do I change one field per cluster without maintaining a copy of the whole object? The README lists them among the new features, and the architecture is the point of the project. The repository carries an examples/scheduler/ directory, which suggests the scheduling behaviour is meant to be exercised with worked examples rather than only described. Follower scheduling handles the case where one workload depends on another, a ConfigMap consumed by a Deployment, or a Service that has to exist before the pods that call it. Automatic propagation of dependencies means the follower object is scheduled and placed when its leader is, rather than being a second thing to remember. That is the difference between a federation controller that propagates objects and one that understands the graph between them. Status aggregation is the third piece, and it is what makes the control plane usable rather than merely correct. Member clusters report back, and the aggregated status of those resources is reflected in the control plane, so an operator sees one view rather than N cluster states. The implementation leans on the Kubernetes API machinery rather than reinventing it. The go.mod pins k8s.io/api, apimachinery, apiserver, client-go and component-base at v0.31.0, uses sigs.k8s.io/controller-runtime for the controller layer, and includes sigs.k8s.io/mcs-api for multi-cluster services and github.com/kubewharf/katalyst-api for the scheduling extensions. ## Building the controller manager from the Makefile The repository builds with Go and a Makefile that drives a script in hack/make-rules/. The simplest build compiles all binaries for the host platform: ```bash # compile all binaries with the host platform make build ``` The available targets are listed in the Makefile as all, kubeadmiral-controller-manager and kubeadmiral-hpa-aggregator, and you can compile one component or cross-compile for several platforms: ```bash make build TARGET_NAME=kubeadmiral-controller-manager make build BUILD_PLATFORMS=linux/amd64,darwin/amd64 ``` Container images are published under the ghcr.io/kubewharf registry, and the Makefile exposes REGISTRY, TAG and REGION as variables, with a REGION of cn switching GOPROXY to a different module proxy. For development there is a local cluster. The dev-up target starts the KubeAdmiral control plane without the controller manager and three member clusters, so the controller manager can be run from a binary for easier debugging: ```bash bash hack/make-rules/dev-up.sh make build-debug ``` The debug build adds the race detector, since the Makefile sets BUILD_FLAGS+=-race for the build-debug target. There is also a codecov configuration and a golangci lint configuration at the top level, with ginkgo and gomega plus testify and go-cmp among the test dependencies, and sigs.k8s.io/kind used for the kind based test clusters. ## A developer cluster with three member clusters The development environment is worth a second look because it tells you what the project assumes about scale. The Makefile comment describes it as starting the KubeAdmiral control plane cluster, excluding the kubeadmiral-controller-manager, along with three member clusters. Users then run the controller manager through the binary so they can attach a debugger or step through code without rebuilding an image. Three member clusters is a deliberate floor, not a ceiling. It is enough to exercise the cases that break naive controllers: one cluster where a workload fits, one where it does not, and one that is unreachable or degraded. Any federation controller that works on three clusters will at least have to deal with partial failure and with the same object landing in places with different capacity. The repository structure follows the same split. cmd/ holds the entry points, pkg/ holds the library code, charts/ holds the Helm charts, config/ the configuration manifests, examples/ the worked examples, hack/ the build scripts, test/ the test assets, and docs/ the documentation including the quickstart referenced from the README. A Makefile, go.mod and go.sum complete the tree, and the governance files GOVERNANCE.md, MAINTAINERS.md, CODE_OF_CONDUCT.md and CONTRIBUTING.md are all present, which says something about how the project intends to be run. ## How KubeAdmiral differs from Karmada The README names Karmada as a reference for architecture and API design, with credits to the Karmada authors. That is the comparison worth making, because both projects solve the same problem and make different bets. The shared premise is that Kubernetes has outgrown single-cluster assumptions, so a layer above the API server is needed to place workloads across many clusters. Both use the native Kubernetes API rather than inventing a parallel resource type, and both place scheduling decisions in a dedicated framework rather than leaving placement to whatever each member cluster's own scheduler does. The difference is lineage and emphasis. KubeAdmiral is a continuation of Kubernetes Federation v2, so its APIs grew out of an existing federated model with the federated types removed, and it carries that history in its API surface. Karmada arrived with its own design, and the README credits it for architectural and API inspiration rather than for code. The practical difference for an adopter is the API you write against and the ecosystem around it. A team that already knows Karmada's scheduling plugins and policies will find familiar concepts in KubeAdmiral's override policies and follower scheduling, and the reverse is also true. Neither project is a drop-in for the other, and switching later means rewriting the policy layer, not just the manifest. ## Kubernetes 1.24 is the ceiling and the release history is thin Two facts should shape your adoption decision. The first is the version window. The README states that KubeAdmiral supports Kubernetes versions from 1.16 up to 1.24, and that using lower or higher versions may cause compatibility issues. Kubernetes 1.24 is well behind current releases, so a new cluster today is likely to be outside that window unless it is pinned to an older release. That is a hard constraint on when you can introduce the tool, not a warning about the future. The second is the release record. The repository is not archived and the last push was on 2026-05-11, but the only release listed is v1.0.0 from 2024-06-18. A single version tag two years old, with commits still arriving on main, describes a project where the moving branch is the delivery mechanism. Anyone pinning versions needs to decide whether to pin the tag and lose later fixes, or track main and accept that the API can change under you. On licensing, the licence field on the repository says Apache-2.0 and the README states KubeAdmiral is under the Apache 2.0 license with details in the LICENSE file. The README also notes that the project is a continuation of Kubernetes Federation v2 and that certain features rely on existing code from Kubernetes, with all credits going to the original Kubernetes authors, and that Karmada is credited for architecture and API design. A NOTICE file sits at the top level alongside the LICENSE, which is where those attributions belong. ## The README tells you to secure it yourself The most consequential line in the README is the warning at the top of the getting started section: if you want to deploy KubeAdmiral into production environments, please add authentication to the website and evaluate your security check of the KubeAdmiral components. That is the project declining to make the production deployment safe for you. The web interface is the control plane through which you push work to every member cluster, and if it ships without authentication, anyone who can reach it can schedule workloads into your fleet. The wording is a warning, not a documented default, and it leaves two questions open: what the components security check consists of, and how to add the authentication. Neither the README nor the quickstart reference quoted here answers them. The docs/ directory is present in the repository and would be where to look, but a reader working from the README alone has to treat the web interface as unauthenticated until proven otherwise and put a front proxy with authentication in front of it. That is not an unusual arrangement for an infrastructure project, but it does move work onto the adopter, and it should be scheduled work rather than a later hardening pass. ## Conclusion KubeAdmiral suits platform teams running several Kubernetes clusters that want one scheduling and propagation surface built on native Kubernetes objects rather than on federated types such as FederatedDeployment. It does not suit clusters above Kubernetes 1.24, and it does not suit anyone who needs the documentation's warning answered for them, since the README asks you to add authentication to the website and evaluate the security of the components yourself before production use. Before adopting, read docs/quickstart.md, confirm every member cluster is between 1.16 and 1.24, and put authentication in front of the KubeAdmiral web interface rather than shipping it as documented. ## FAQ ### What is KubeAdmiral and how does it differ from Kubernetes Federation v2? KubeAdmiral is a multi-cluster management system for Kubernetes developed from Kubernetes Federation v2. It extends the Federation v2 API while keeping compatibility with the Kubernetes native API, and adds a new scheduling framework, override policies, follower scheduling and status aggregation of member cluster resources. ### Which Kubernetes versions does KubeAdmiral support? The README states that KubeAdmiral supports Kubernetes versions from 1.16 up to 1.24, and that using lower or higher versions may cause compatibility issues. ### How do I build KubeAdmiral from source? Use the Makefile. make build compiles all binaries for the host platform, make build TARGET_NAME=kubeadmiral-controller-manager builds a single component, and make build BUILD_PLATFORMS=linux/amd64,darwin/amd64 cross-compiles for several platforms. ### Is KubeAdmiral safe to run in production as documented? The README carries a warning that if you deploy KubeAdmiral into production you should add authentication to the website and evaluate your security check of the KubeAdmiral components. Treat the web interface as unauthenticated until you have added your own access control. ### What licence is KubeAdmiral released under? The licence field on the repository says Apache-2.0, and the README states KubeAdmiral is under the Apache 2.0 license with details in the LICENSE file. The README also credits the original Kubernetes authors for code carried over from Federation v2 and the Karmada authors for architecture and API design. ## Sources - [kubewharf/kubeadmiral on GitHub](https://github.com/kubewharf/kubeadmiral) - [License: Apache-2.0](https://github.com/kubewharf/kubeadmiral/blob/main/LICENSE) - [Project website](https://kubeadmiral.io) - [README](https://github.com/kubewharf/kubeadmiral/blob/main/README.md) - [Releases](https://github.com/kubewharf/kubeadmiral/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubewharf-kubeadmiral