Support cluster-scoped resources in controller sharding

[cappyzawa]

What would you like to be added:

Support for cluster-scoped resources (like Namespace, Node, ClusterRole, CustomResourceDefinition, etc.) in controller sharding.

Why is this needed:

Currently, controller sharding only works with namespace-scoped resources. However, most of the sharding infrastructure already supports cluster-scoped resources - there's just one filtering issue preventing it from working.

This would be useful for namespace management at scale (control plane clusters serving thousands of namespaces, K8s-as-a-Service providers), managing nodes in large clusters, or distributing RBAC operations across ClusterRole controllers.

Looking at the code, most components already work fine - the hash key generation already handles cluster-scoped resources, the webhook works with any GroupResource type, and the controller library handles both scoped types correctly. The only issue is in the sharder controller where cluster-scoped resources get filtered out:

if !o.Namespaces.Has(obj.GetNamespace()) {
    return nil // cluster-scoped resources have empty namespace, always skipped
}

This requires two complementary changes. First, modify the namespace filtering to allow cluster-scoped resources:

// Current implementation
if !o.Namespaces.Has(obj.GetNamespace()) {
    return nil
}

// Proposed fix
if obj.GetNamespace() != "" && !o.Namespaces.Has(obj.GetNamespace()) {
    return nil
}

Second, fix the hash key generation issue.

Current hash key format group/kind/namespace/name creates inconsistencies when Namespace itself is a sharding target:

// Namespace "sandbox" hash key: "//Namespace//sandbox"  
// Pod controlled by Namespace "sandbox": "//Namespace/sandbox/sandbox"

Proposed hash key improvement using controller-runtime's official API:

func ForObject(obj client.Object, scheme *runtime.Scheme, restMapper meta.RESTMapper) (string, error) {
    gvk := obj.GetObjectKind().GroupVersionKind()
    // ...existing validation...

    // Use controller-runtime's official scope detection
    isNamespaced, err := apiutil.IsObjectNamespaced(obj, scheme, restMapper)
    if err != nil {
        return "", fmt.Errorf("error determining object scope: %w", err)
    }

    if isNamespaced {
        return gvk.Group + "/" + gvk.Kind + "/" + obj.GetNamespace() + "/" + obj.GetName(), nil
    }
    // cluster-scoped: exclude namespace component  
    return gvk.Group + "/" + gvk.Kind + "/" + obj.GetName(), nil
}

This approach uses controller-runtime's standard scope detection, works with custom resources, and fixes the hash key consistency issue where Namespace "sandbox" and its controlled objects would end up with the same key.

Since the project is not yet production-ready, this breaking change to hash key generation should be acceptable.

Does this align with the project's design philosophy? I see this is already in the backlog (kubernetes-controller-sharding (view)), so I wanted to confirm there are no design considerations that would make this implementation inappropriate.

[yuanying]

We are working on introducing sharding into our private Kubernetes-based platform and are currently testing several approaches.

One of our approaches is to divide shards at the namespace level and run a controller for each namespace assigned to a given controller.

If there are any technical reasons why kubernetes-controller-sharding does not support cluster-scoped sharding, we would greatly appreciate it if you could share them.

• This issue is related to Multi-level ownership for controller sharding #664

[timebertt]

Thanks, your suggestions sound good to me. I'd be happy to review a PR :)

[timebertt]

When introducing this feature, it would be beneficial to cover it in e2e tests. I.e., adding a working example in the checksum-controller should ensure we don't break this case.

[yuanying]

Sorry for our late reply, and the for the quick feedback and for asking us to include e2e coverage.

So, currently we plan adding a small, purpose-built test controller for cluster-scoped resources instead of extending checksum-controller, keeping it unchanged helps avoid widening its scope and breaking the current getting-started flow/docs.

Our proposal is:

• Introduce a minimal controller that reconciles a cluster-scoped type (e.g., Namespace) and performs a simple, observable action (e.g., set/update an annotation), used only by the e2e suite.
• Place it under something like cmd/cluster-scoped-controller (or a test/controllers path—happy to follow your preference), wire it into make test-e2e, and document usage in the e2e README.
• Keep existing checksum-controller behavior and tests untouched.

If that sounds good, we’ll proceed with this approach. If you’d rather see the cluster-scoped behavior folded into checksum-controller, we can adapt—just let us know your preferred location/naming.