Proposal: Integrate Kubernetes Controller Sharding (timebertt/kubernetes-controller-sharding) into Kubebuilder

[kersten]

I recently attended a fantastic demo talk at KubeCon London where timebertt/kubernetes-controller-sharding was showcased. This project enables horizontally scalable controllers by sharding reconciliation across multiple active instances. Traditional leader election (one leader at a time) can become a bottleneck for large-scale operators, whereas sharding splits objects among replicas in an active-active fashion.

Why Consider This for Kubebuilder?

• Improved Scalability & Throughput: Multiple controller replicas can share the workload, each reconciling only a subset of objects.
• High Availability: With active-active shards, if one shard goes down, only a fraction of objects is affected until the shard recovers or objects are re-assigned.
• Compatible with controller-runtime: The library reuses Kubernetes primitives (Leases, consistent hashing, label selectors) and integrates with the same manager abstractions Kubebuilder already uses.
• Selective Data Caching: Each shard only watches the portion of objects it owns. This can reduce memory usage per instance, which helps in large-scale scenarios.

Points to Note

• The project is in alpha (v0.10.0). The CRD is v1alpha1.
• The approach relies on a sharder component (plus a mutating webhook) to label objects and coordinate shard membership.
• Integrating with Kubebuilder would require optional scaffolding changes (setting up the sharding CRD, adjusting controller watchers, etc.).
• This introduces extra complexity (another controller for the sharder, new CRD) but unlocks horizontal scaling for those who need it.

Request for Feedback

1. Does the community see value in integrating controller sharding as a first-class or optional Kubebuilder feature?
2. Would you be open to a feature flag extension in Kubebuilder for easy sharding support?
3. Are there concerns about operational overhead, alpha-stage maturity, or the mutating webhook approach?

[everpeace]

+1 for this proposal!!

Extra note: I think this implementation is carefully designed so that

• Sharder's responsibility is minimal. This means that sharder won't be a bottleneck for most cases.
• Shard management is really safe
  • handing over shards between controllers can be done safely by getting ack via object labels (as presented his kubecon talk)
  • no multiple controllers reconciles the same object at any time (note: zero controller could be happened when no active sharder runs)

[camilamacedo86]

Hi @kersten, @everpeace

Thanks a lot for sharing this — it's a very interesting and well-thought-out project that solves a real problem at scale.

That said, we don’t see a strong reason to include controller sharding into the default Kubebuilder scaffold at this time.

Kubebuilder’s goals are very specific:

• Welcome beginners to the Kubernetes ecosystem.
• Help developers with the most common use cases (~80% of scenarios).
• Keep the scaffolding simple, low in complexity, and aligned with best practices from controller-runtime.

---

❌ Why we should not integrate this into the default scaffold:

• Sharding is a special case, not a general need. It's very useful for high-scale operators, but most controllers never need horizontal scalability beyond leader election.
• It introduces additional complexity (e.g. a new CRD, mutating webhook, sharder controller) that would confuse or overwhelm many users.
• We have a policy of avoid introducing dependencies on:
  • Projects outside of the kubernetes-sigs organization. ( unless they are mature, the most commonly used solutions such as Docker and cert-manager )
  • Experimental or niche libraries that aren't widely adopted and stable.
  • Do not create internal plugins for external third-party API solutions ( those should be within the third-party API solutions themselves)

---

✅ What we do support:

We encourage the community to build a Kubebuilder plugin for controller sharding ( if that is desired )

Kubebuilder supports external plugins very well, and this use case is a great fit.

🔧 Start here:

• 📘 Plugin guide: https://kubebuilder.io/plugins/extending
• 🔌 External plugins: https://kubebuilder.io/plugins/extending/external-plugins

The plugin should live in the controller-sharding project itself, not in the Kubebuilder repo. This ensures:

• Updates to the plugin can be made independently.
• Ownership stays with the team that best understands the design and maintenance of the sharding approach.
• Kubebuilder maintainers are not responsible for maintaining niche logic or advanced operator patterns.

We currently do not have bandwidth, expertise, or long-term maintenance capacity for such a plugin ourselves.

---

✅ Final Thoughts

We're more than happy to support anyone interested in building and maintaining such a plugin — whether it's the project authors or someone else in the community.

Kubebuilder can be used as a library, and plugin authors can fully customize the scaffold to support advanced setups like this.

Thanks again for bringing this forward !