:sparkles: add a controller-name for multi-controller by guilhem · Pull Request #5474 · kubernetes-sigs/kubebuilder

guilhem · 2026-02-13T11:39:35Z

Naive implementation of #5473

This pull request introduces support for scaffolding multiple controllers for the same Group/Version/Kind (GVK) in Kubebuilder, allowing users to split reconciliation responsibilities, run different reconciliation modes, or manage migration scenarios. The main enhancement is the addition of the --controller-name flag to the create api command, along with corresponding updates to documentation, configuration, and code generation logic.

Feature: Multiple Controllers for the Same GVK

Added support for the --controller-name flag in create api, enabling scaffolding of additional controllers for an existing API. Each controller gets its own file, struct, and unique registration, and the controller name is tracked in the PROJECT file. [1] [2] [3] [4] [5]
Updated the resource model and configuration logic to allow multiple entries for the same GVK with different controller names, including proper handling in resource addition and updating. [1] [2] [3] [4] [5] [6]
Improved code generation to use the controller name for file naming, struct naming (PascalCase conversion), and registration, and updated templates and replacers accordingly. [1] [2] [3] [4] [5]

Validation and CLI Enhancements

Added validation for the controller name to ensure it conforms to DNS-1035 label requirements, and integrated the flag into the CLI and scaffolding logic. [1] [2] [3]

Documentation Updates

Expanded documentation to describe the new feature, including use cases, configuration examples, and instructions for tracking controller names in the PROJECT file. [1] [2] [3] [4] [5]

Code Generation and Template Changes

Updated scaffolding logic and templates to support multiple controllers, including changes to cmd/main.go and controller test files. [1] [2]

These changes make Kubebuilder more flexible for advanced controller patterns and improve clarity and maintainability in projects with complex reconciliation needs.

Fix kubernetes-sigs#5473 Signed-off-by: Guilhem Lettron <glettron@akamai.com>

k8s-ci-robot · 2026-02-13T11:39:43Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: guilhem
Once this PR has been reviewed and has the lgtm label, please assign camilamacedo86 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 · 2026-02-13T11:39:44Z

Welcome @guilhem!

It looks like this is your first PR to kubernetes-sigs/kubebuilder 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/kubebuilder has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2026-02-13T11:39:45Z

Hi @guilhem. 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. Regular contributors should join the org to skip this step.

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 · 2026-02-13T11:50:04Z

docs/book/src/reference/project-config.md

+    kind: Memcached
+    path: example.com/memcached-operator/api/v1alpha1
+    version: v1alpha1
+  - controller: true


How it would be if instead of replicated GKV for each controller
we have:
controller
name:

nameA

nameB

nameC

I think that would be a more clean structure
It would either facilitate the implementation for alpha generate.
WDYT?

That's a cleaner structure indeed :)

Is something like that ok?

controllers: - name: nameA - name: nameB - name: nameC

It gives the opportunity to add more fields in the future for each controllers.

or, if we want to prevent an array:

controllers: nameA: {} nameB: {} nameC: {}

I just fear when using the cli:
When the first name hasn't been set, we will have to set "nameA" to the first computed and nameB to the one set.
(not really a problem, just something to do)

When the first name hasn't been set, we will have to set "nameA" to the first computed and nameB to the one set.

We have a method that do the "merge" of GKV.
I think we need to have exactly the same but for the new Controller as well.

We will need to think a lot here to ensure that we have a great API
Because we cannot change easily those after we release the changes.

So maybe it will be acctually like

resource: controller: - name: A controller: -Name B

The list I think should be of controllers.
ONE API/GKV can have MANY controllers ;-)

So that tomorrow we can either

resource: controller: - name: A - key: value - key: value controller: -Name B

Signed-off-by: Guilhem Lettron <glettron@akamai.com>

camilamacedo86 · 2026-02-13T11:50:49Z

docs/book/src/reference/project-config.md

 | `resources.api.crdVersion`          | The Kubernetes API version (`apiVersion`) used to do the scaffolding for the CRD resource.                                                                                                                                                                                      |
 | `resources.api.namespaced`          | The API RBAC permissions which can be namespaced or cluster scoped.                                                                                                                                                                                                             |
 | `resources.controller`              | Indicates whether a controller was scaffolded for the API.                                                                                                                                                                                                                      |
+| `resources.controllerName`          | **(Optional)** A custom name for the controller, provided via the `--controller-name` flag. When set, it allows multiple controllers for the same GVK. The name is used for the controller file name, the reconciler struct name, and the controller's `Named()` registration. Must be a DNS-1035 label (lowercase alphanumeric and hyphens). |


Let's try check out it with a list of Namespaces

controller.names LIST
WDYT?

camilamacedo86 · 2026-02-13T11:52:24Z

pkg/config/v3/config.go


 	for i, r := range c.Resources {
-		if res.IsEqualTo(r.GVK) {
+		if res.IsEqualTo(r.GVK) && res.ControllerName == r.ControllerName {


I think we need a method to check in the LIST something like
resource.HasControllerName()

camilamacedo86 · 2026-02-13T11:53:06Z

pkg/config/v3/config_test.go

+							API:            &resource.API{CRDVersion: "v1", Namespaced: true},
+						},
+						{
+							GVK: resource.GVK{


We should not duplicate the GKV we could not have more than one on the cluster less yet in the project

camilamacedo86 · 2026-02-13T11:54:07Z

pkg/plugins/golang/v4/api.go

+	// Validate controller name if provided
+	if p.options.ControllerName != "" {
+		if !p.options.DoController {
+			return errors.New("cannot use '--controller-name' with '--controller=false'")


Valiations should be in the preScaffold
We probably need to add this one inside of the method that validate GKV already

camilamacedo86 · 2026-02-13T11:54:23Z

pkg/plugins/golang/v4/api.go

+		}
+		if errs := validation.IsDNS1035Label(p.options.ControllerName); len(errs) != 0 {
+			return fmt.Errorf("invalid controller name %q: must be a DNS-1035 label "+
+				"(lowercase, alphanumeric, hyphens, starting with a letter)", p.options.ControllerName)


camilamacedo86 · 2026-02-13T11:55:18Z

pkg/plugins/golang/v4/api.go

 	}

+	// When adding a named controller for an existing GVK, skip API re-scaffolding
+	if p.options.ControllerName != "" && p.options.DoAPI {


I think it is not accurate.
At the same way that we have many controllers for a core API we should be able to have many controllers for a external type too.

camilamacedo86 · 2026-02-13T11:56:34Z

pkg/plugins/golang/options.go


+	// ControllerName is an optional custom name for the controller.
+	// When set, allows scaffolding multiple controllers for the same GVK.
+	ControllerName string


Lets try to do a list
But we need to properly think in how we will design the API here
I think we will need a new struct Controller and then inside of it we add name

Therefore, in the future we can add other specs for Controller if we have the need.

I totally agree

camilamacedo86

HI @guilhem

Thank you for looking on that.
I did some comments.
Mainly IHMO:

The API must be a design choice that allow us to grow if we need. So we will probably need to have a new struct Controller inside of Resources and that allows pass a List of names.
The validations for GKV need to be done in the preScaffold. Those should be in the funcs that we have already today in the API
We will need either ensure that alpha generate work with. So, if we have resources.Crontroller.names we should call create api resource false and controller true with the name for each name after create the API.

Signed-off-by: Guilhem Lettron <glettron@akamai.com>

k8s-ci-robot · 2026-02-13T14:32:43Z

Keywords which can automatically close issues and hashtag(#) mentions are not allowed in commit messages.

The list of commits with invalid commit messages:

6829f40 feat: add a controller-name for multi-controller

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. I understand the commands that are listed here.

guilhem · 2026-02-13T14:55:38Z

@camilamacedo86 I changed to new API for PROJECT and passed this PR as a draft to be certain it's not merged until the API is stabilized.

k8s-ci-robot · 2026-02-28T04:25:15Z

PR needs rebase.

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.

feat: add a controller-name for multi-controller

6829f40

Fix kubernetes-sigs#5473 Signed-off-by: Guilhem Lettron <glettron@akamai.com>

k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 13, 2026

k8s-ci-robot requested review from camilamacedo86 and vitorfloriano February 13, 2026 11:39

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Feb 13, 2026

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 13, 2026

camilamacedo86 reviewed Feb 13, 2026

View reviewed changes

test: controller-name

eea0e66

Signed-off-by: Guilhem Lettron <glettron@akamai.com>

camilamacedo86 reviewed Feb 13, 2026

View reviewed changes

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 13, 2026

camilamacedo86 reviewed Feb 13, 2026

View reviewed changes

camilamacedo86 requested changes Feb 13, 2026

View reviewed changes

feat: use a "controllers" array for all contr

5600705

Signed-off-by: Guilhem Lettron <glettron@akamai.com>

k8s-ci-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Feb 13, 2026

guilhem marked this pull request as draft February 13, 2026 14:32

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Feb 13, 2026

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 28, 2026

Conversation

guilhem commented Feb 13, 2026

Uh oh!

k8s-ci-robot commented Feb 13, 2026

Uh oh!

k8s-ci-robot commented Feb 13, 2026

Uh oh!

k8s-ci-robot commented Feb 13, 2026

Uh oh!

camilamacedo86 Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guilhem Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guilhem Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Feb 13, 2026

Uh oh!

guilhem commented Feb 13, 2026

Uh oh!

k8s-ci-robot commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

camilamacedo86 Feb 13, 2026 •

edited

Loading

guilhem Feb 13, 2026 •

edited

Loading

guilhem Feb 13, 2026 •

edited

Loading

camilamacedo86 Feb 13, 2026 •

edited

Loading