Multicluster Support for KRO

[mjudeikis]

Feature Description

Feature Request: Multicluster Support for KRO

Problem Statement:

KRO currently operates on a single Kubernetes cluster. Users who manage multiple clusters must deploy and configure KRO separately on each cluster. This creates operational overhead and prevents centralized management of ResourceGraphDefinitions across a fleet of clusters.

Organizations run workloads across multiple clusters for geographic distribution, environment separation, team isolation, or high availability. These users need a way to define resources once and deploy them across multiple clusters from a single control plane.

Proposed Solution:

Add multicluster support to KRO using a hub-spoke model:

• Hub cluster: Runs KRO controller and stores ResourceGraphDefinitions (RGDs)
• Spoke clusters: Receive generated CRDs and run instances with their child resources

Key design points:

• Use multicluster-runtime (MCR) library as a drop-in replacement for controller-runtime
• Cluster discovery via pluggable providers (starting with kubeconfig secrets)
• RGDs defined only in hub, CRDs and instances live in spokes
• Opt-in via --enable-multicluster flag (backward compatible)

Alternatives Considered:

• Separate KRO per cluster: Current approach. Simple but creates operational overhead and prevents centralized management. And clusters can't be just controlplanes, and not all clusters can be controlplanes, so this is not a viable long-term solution.
• GitOps-based distribution: Use ArgoCD to deploy RGDs to multiple clusters. Adds complexity and another tool dependency. No unified status visibility. Still required per-cluster KRO instances.

Additional Context:

What is multicluster for KRO?

Proposed definition: Multicluster for KRO means the ability to manage ResourceGraphDefinition instances and their child resources across multiple Kubernetes clusters from a single KRO control plane. Keeping RGDs centralized in a hub cluster while distributing CRDs and instances to spoke clusters where workloads run.

Specifically:

• One hub, many spokes: A single KRO controller runs in a hub cluster and connects to multiple spoke clusters
• Definitions stay central: RGDs are authored and stored only in the hub cluster
• Resources are distributed: CRDs and instances live in spoke clusters where workloads run
• Same-cluster locality: All child resources of an instance are created in the same spoke cluster as the instance itself (no cross-cluster dependencies)

What multicluster is not for KRO:

• Federation or replication of RGDs across clusters
• Cross-cluster resource references (e.g., a Deployment in cluster-A referencing a ConfigMap in cluster-B)
• Running multiple KRO controllers that coordinate with each other
• Cluster lifecycle management (creating/deleting clusters)

┌─────────────────────────────────────────────────────────┐
│                      Hub Cluster                        │
│  ┌─────────────────┐  ┌────────────────┐  ┌───────────┐ │
│  │      RGDs       │  │ KRO Controller │  │  Cluster  │ │
│  │  (definitions)  │──│ (multicluster) │──│  Secrets  │ │
│  └─────────────────┘  └───────┬────────┘  └───────────┘ │
└───────────────────────────────│─────────────────────────┘
                                │
         ┌──────────────────────┼──────────────────────┐
         │                      │                      │
         ▼                      ▼                      ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Spoke Cluster  │    │  Spoke Cluster  │    │  Spoke Cluster  │
│  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
│  │   CRDs    │  │    │  │   CRDs    │  │    │  │   CRDs    │  │
│  │ Instances │  │    │  │ Instances │  │    │  │ Instances │  │
│  │  + Child  │  │    │  │  + Child  │  │    │  │  + Child  │  │
│  │ Resources │  │    │  │ Resources │  │    │  │ Resources │  │
│  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Terminology:

• Hub cluster: The cluster running KRO controller and storing RGDs
• Spoke cluster: A remote cluster where CRDs and instances are deployed
• MCR: multicluster-runtime (sigs.k8s.io/multicluster-runtime)

Initial scope:

• Kubeconfig provider for cluster discovery
• DynamicController multicluster awareness
• Cluster-aware client factory

Out of scope for initial implementation:

• Cross-cluster resource dependencies
• Cluster API provider
• Per-cluster RGD targeting

---

Discussion and notes

• Mangirdas Judeikis Proposed this on Feb 18, 2028 via
  in the community meeting & POC work - https://github.com/mjudeikis/kro/tree/mcr.poc

• Please vote on this issue by adding a 👍 reaction to the original issue

[jakobmoellerdev]

I am all for this proposal and a KREP.
Main concerns that need dedicated covering:

• stability guarantees
• testing setup and infra for multi cluster
• version compatibility across differing api server versions (cel expressions will always be evaled based on hub cluster, not spoke)
• performance considerations around dynamic controller scaling

[mjudeikis]

So to answer some of the questions:

stability guarantees

We are just a wrapper around controller-runtime, so you get same as you get from controller-runtime

testing setup and infra for multi cluster

noted. Kind cluster does job quite well for this for us too.

version compatibility across differing api server versions (cel expressions will always be evaled based on hub cluster, not the spoke)

I would put this out of scope, as it should be the user's responsibility to make sure that "spoke" clusters are compatible with the hub cluster in terms of versioning. We could hardcode some k8s version checking, saying - "if you are lower than X, we don't admin the cluster into runtime".

performance considerations around dynamic controller scaling

I think this is a valid case, but very hard to estimate without real-world scenarios. But if we land this feature, I think we can try to perform-test this quite fast.

[JamesGAWS]

I've been working on a KREP for this topic and put in the PR last Friday: #1064

The KREP has the cluster references defined in the RGD and extends beyond just multi-cluster, to the topic of multi-protocol; ie KRO working with any RESTFUL resource (HTTP, gRPC, git, etc).

It resolves all the requests laid on in this issue except for the cross cluster Instance object, which is addressed as part of future directions.

I'm not sure if the KREP addresses this concern:

Cluster discovery via pluggable providers (starting with kubeconfig secrets)

Can you explain a little more here?

[mjudeikis]

Cluster discovery via pluggable providers (starting with kubeconfig secrets)

multicluster-runtime sole purpose is to be a pluggable framework to be able to use a single reconciliation loop across many clusters, based on provider (see multicluster-runtime providers dir https://github.com/kubernetes-sigs/multicluster-runtime/tree/main/providers). Your provider can be backed any anything, as long as you can derive rest.Config from it.

The main idea is that it's transparent to the API, as it operates at the reconcile loop level, not the API.