✨ (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.

[camilamacedo86]

HI @v47

I am finding a hard time to check the real delta from an defult scaffold and this one.
Would only be this line and the secret?

[v47]

The single most important change is swapping ctrl.NewManager(...) for mcmanager.New(cfg, provider, ...). That one line is what makes the whole thing multicluster-aware — instead of a manager that knows about one cluster, you get a manager that knows about all clusters registered with the chosen provider. Everything else in cmd/main.go is either plumbing to support that, or unchanged boilerplate.
The second piece is the provider itself. Depending on which --provider has been chosen, you get a few lines to construct and start it — for example, kubeconfigprovider.New(...) followed by provider.SetupWithManager(ctx, mgr). For the namespace and file providers, the startup is slightly different (they need to run concurrently with the manager via errgroup), but conceptually it's the same idea. Wire up the configuration that tells the manager which clusters exist.
The ctrl.GetConfigOrDie() call is also replaced with an explicit ctrl.GetConfig() + error check, which is a minor style difference.

[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.

[Copilot]

Pull request overview

Adds a new optional Kubebuilder plugin (multicluster-runtime/v1-alpha) intended to rewrite a go/v4-scaffolded project to use sigs.k8s.io/multicluster-runtime (multicluster manager + multicluster-aware controllers), along with documentation and E2E coverage.

Changes:

• Introduces pkg/plugins/optional/multicluster-runtime/v1alpha with init/edit/create-api behavior, scaffolds, and unit tests.
• Adds scaffolding templates for multicluster-aware cmd/main.go, controllers, and controller tests, plus a main.go updater for wiring controllers.
• Registers the plugin in the CLI, adds a new book page, and adds E2E tests for kubeconfig + namespace providers.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/e2e/all/plugin_multicluster_test.go	New E2E coverage for init/create-api/edit with the multicluster plugin.
pkg/plugins/optional/multicluster-runtime/v1alpha/suite_test.go	Ginkgo suite for plugin unit tests.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/internal/templates/controllers/controller.go	Multicluster-aware controller template (mcreconcile + mcbuilder).
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/internal/templates/controllers/controller_test_template.go	Controller test template adjusted to use mcreconcile.Request.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/internal/templates/cmd/main.go	Provider-specific cmd/main.go templates using mcmanager.New.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/internal/templates/cmd/main_updater.go	Inserter to wire controller setup into the multicluster main template.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/init.go	Init scaffolder that overwrites go/v4’s main.go and pins multicluster-runtime version.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/edit.go	Edit scaffolder to switch providers by rewriting cmd/main.go.
pkg/plugins/optional/multicluster-runtime/v1alpha/scaffolds/api.go	API scaffolder that overwrites controller + unit tests and wires main.go.
pkg/plugins/optional/multicluster-runtime/v1alpha/plugin.go	Plugin entry point (Init/CreateAPI/Edit) and metadata.
pkg/plugins/optional/multicluster-runtime/v1alpha/plugin_test.go	Unit tests for plugin metadata and subcommands.
pkg/plugins/optional/multicluster-runtime/v1alpha/init.go	kubebuilder init subcommand implementation (+ go get/tidy).
pkg/plugins/optional/multicluster-runtime/v1alpha/init_test.go	Unit tests for init defaults and provider validation.
pkg/plugins/optional/multicluster-runtime/v1alpha/helpers.go	Provider validation helper.
pkg/plugins/optional/multicluster-runtime/v1alpha/edit.go	kubebuilder edit subcommand implementation (+ go get/tidy).
pkg/plugins/optional/multicluster-runtime/v1alpha/edit_test.go	Unit tests for edit defaults and scaffold output.
pkg/plugins/optional/multicluster-runtime/v1alpha/api.go	kubebuilder create api subcommand implementation.
pkg/plugins/optional/multicluster-runtime/v1alpha/api_test.go	Unit tests ensuring multicluster controller scaffold output.
internal/cli/cmd/cmd.go	Registers the new optional plugin in the built-in CLI plugin list.
docs/book/src/plugins/extending/multicluster-runtime-plugin.md	New documentation page describing usage and providers.