✨ (multicluster-runtime/v1-alpha): Add multicluster-runtime optional plugin

[v47]

Description

Adds a new optional plugin multicluster-runtime/v1-alpha at pkg/plugins/optional/multicluster-runtime/v1alpha/ that rewrites a Kubebuilder project to use sigs.k8s.io/multicluster-runtime instead of the standard single-cluster controller-runtime manager.

The plugin is designed to chain after go/v4:

kubebuilder init --plugins go/v4,multicluster-runtime/v1-alpha \
  --domain example.com --repo github.com/example/myop \
  --provider kubeconfig

Motivation

Multi-cluster operators are increasingly common (Cluster API, KCP, Open Cluster Management, fleet controllers), yet writing one today requires manually wiring sigs.k8s.io/multicluster-runtime. This plugin lowers the barrier to zero: one kubebuilder init command produces a compiling, runnable multicluster operator.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: v47
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Hi @v47. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[camilamacedo86]

Is the motivation here scaffold it only or has any other difference with this option?

[v47]

It keeps the version in the doc, and the go get from scaffolds.MulticlusterRuntimeVersion so they stay in sync. There is no GoMod template here because this plugin chains after go/v4, which already created go.mod. Overwriting via a template would erase everything go/v4 put there.

[vitorfloriano]

Awesome! I didn't even know sigs.k8s.io/multicluster-runtime existed before this PR. Really cool stuff. Thanks for bringing it up.

But, I have some thoughts on this:

First, it seems multicluster-runtime is a project in its early stages (created around Feb 2025), is not stable (as per SemVer conventions), and that's still gaining traction.

Second, why not build this as an external plugin, instead of in-tree? I'm not sure if this solves a recurrent painpoint for developers or if it's more like an edge case.

Besides that, every in-tree plugin we bundle with the kubebuilder binary adds on to the burden on maintainers. Unless we deem this as a common need, it's hard to justify this addition to the tree.

Personally, if I could I would even go further as to reimplement some existent in-tree plugins as external ones (I'm looking at you, grafana and deploy-image!), fulfilling the original vision for plugins, but I guess Camila would stop me. 😅😅

Again, this is an excellent case for a plugin, I'm just not sure if this should live in this repo.

[v47]

Awesome! I didn't even know sigs.k8s.io/multicluster-runtime existed before this PR. Really cool stuff. Thanks for bringing it up.

But, I have some thoughts on this:

First, it seems multicluster-runtime is a project in its early stages (created around Feb 2025), is not stable (as per SemVer conventions), and that's still gaining traction.

Second, why not build this as an external plugin, instead of in-tree? I'm not sure if this solves a recurrent painpoint for developers or if it's more like an edge case.

Besides that, every in-tree plugin we bundle with the kubebuilder binary adds on to the burden on maintainers. Unless we deem this as a common need, it's hard to justify this addition to the tree.

Personally, if I could I would even go further as to reimplement some existent in-tree plugins as external ones (I'm looking at you, grafana and deploy-image!), fulfilling the original vision for plugins, but I guess Camila would stop me. 😅😅

Again, this is an excellent case for a plugin, I'm just not sure if this should live in this repo.

I agree that long-term, this sounds like a good external plugin candidate, or it can be a flag to select a runtime in future versions of the go plugin.

However, I think there is a practical gap today: the external plugin ecosystem/discovery path does not seem mature yet. #4828 is still open and is specifically about starting to track/promote external plugins, possibly later through an “External Plugins” or “Ecosystem” docs section. So today, there is not really an established place where users discover these plugins.

Also, unlike Terraform providers, Kubebuilder does not currently have a mature dynamic plugin resolution/installation flow where a project can declare an external plugin and the CLI fetches/runs it automatically. The Phase 2 design points in that direction, but it is still marked as partially implemented.

That is why I proposed this in-tree under optional: not because it must live in-tree forever, but because right now that is the only discoverable and reliably usable path for Kubebuilder users.

I am open to moving it external once there is a clear external plugin distribution/discovery story. But until then, making it only external may make it effectively invisible to most users, which weakens the value of having the plugins at all 😞

[vitorfloriano]

the external plugin ecosystem/discovery path does not seem mature yet.

I agree with you here. Kubebuilder lacks some of the amenities that other plugin-based CLIs have: a plugin manager (see kubectl and krew), a plugin registry (again, krew), extensive documentation...and that's on us (maintainers).

But I also think that at this stage we need more people experimenting with external plugins, trying stuff out, breaking things, then filing issues and opening PRs.

It's a bit of a conundrum to me: we don't have a mature plugin ecosystem because we don't have...developers making external plugins. Right now, it seems that developers prefer forking kubebuilder to add their plugins in-tree than building external ones, and that's also a clear sign that something is missing.

All that being said, considering that the proposed plugin revolves around a kubernetes-sigs endorsed tool (not a third party), perhaps it does have its place in-tree. I'm just being wary about adding it because we (the maintainers) are the ones to maintain it, after all. But there's clearly value there.

Thanks for the feedback on the external plugin system/ecosystem. It does need more attention.