✨ feat: Add optional roleName parameter to RBAC marker

[AlirezaPourchali]

Problem

When using namespace-scoped RBAC markers with different namespaces, controller-gen generates multiple Roles with identical names in different namespaces:

# Generated from markers
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: manager-role  # ← Same name
  namespace: infrastructure
rules: [...]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: manager-role  # ← Same name
  namespace: users
rules: [...]

While this is valid Kubernetes, it causes kustomize to fail when applying a global namespace transformation:

Error: namespace transformation produces ID conflict: 
[{"kind":"Role","metadata":{"name":"manager-role","namespace":"myproject-system"}...}
 {"kind":"Role","metadata":{"name":"manager-role","namespace":"myproject-system"}...}]

Both Roles end up in the same namespace with identical names → conflict!

Reported in: kubernetes-sigs/kubebuilder#5148
Follow up from: #1329

Solution

This PR adds an optional roleName parameter to the RBAC marker, allowing users to specify custom role names per marker:

// +kubebuilder:rbac:groups=apps,namespace=infrastructure,roleName=infra-manager,resources=deployments,verbs=get;list
// +kubebuilder:rbac:groups="",namespace=users,roleName=user-secrets,resources=secrets,verbs=get

Generated output:

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: infra-manager  # ← Unique name
  namespace: infrastructure
rules: [...]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: user-secrets  # ← Unique name
  namespace: users
rules: [...]

Now kustomize's namespace transformation succeeds:

# After: namespace: myproject-system transform
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: infra-manager  # ← Different names
  namespace: myproject-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: user-secrets  # ← Different names
  namespace: myproject-system

✅ No conflicts!

Key Features

1. Non-breaking (100% backward compatible)

If roleName is not specified, behavior is identical to current implementation:

// Existing marker (no roleName specified)
// +kubebuilder:rbac:groups=apps,namespace=prod,resources=deployments,verbs=get

// Generated Role uses default from --roleName flag (same as before)
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: manager-role  # ← Uses default
  namespace: prod

2. Opt-in when needed

Only specify roleName when you need unique names:

// Use custom name only where you need it
// +kubebuilder:rbac:groups=apps,namespace=infra,roleName=infra-mgr,resources=deployments,verbs=get
// +kubebuilder:rbac:groups=apps,namespace=prod,resources=deployments,verbs=get  // ← Uses default

3. Marker merging still works

Multiple markers with the same roleName in the same namespace are merged (as expected):

// These merge into one Role named "infra-manager"
// +kubebuilder:rbac:groups=apps,namespace=infrastructure,roleName=infra-manager,resources=deployments,verbs=get;list
// +kubebuilder:rbac:groups=apps,namespace=infrastructure,roleName=infra-manager,resources=statefulsets,verbs=get;list

This PR addresses all the concerns while still solving the original problem.

Testing

Added comprehensive tests in pkg/rbac/testdata/:

1. Custom roleName: Roles get specified names
2. No roleName (backward compat): Roles use default name
3. Marker merging: Multiple markers with same roleName merge correctly
4. Multiple namespaces: Each namespace:roleName combination creates separate Role

All existing tests pass unchanged, confirming backward compatibility.

Implementation Details

• Modified Rule struct to include optional RoleName string field
• Updated GenerateRoles() to group by (namespace, roleName) instead of just namespace
• Added helper documentation explaining the use case and conflict scenario
• Zero changes to CLI or default behavior

Migration Path for Affected Users

Users currently hitting the kustomize conflict can add roleName to their markers:

Before (conflicts):

// +kubebuilder:rbac:groups=apps,namespace=infrastructure,resources=deployments,verbs=get
// +kubebuilder:rbac:groups="",namespace=users,resources=secrets,verbs=get

After (no conflicts):

// +kubebuilder:rbac:groups=apps,namespace=infrastructure,roleName=infra-mgr,resources=deployments,verbs=get
// +kubebuilder:rbac:groups="",namespace=users,roleName=user-secrets,resources=secrets,verbs=get

Run make manifests, commit the updated RBAC YAML, and deploy. No other changes needed.

[k8s-ci-robot]

Welcome @AlirezaPourchali!

It looks like this is your first PR to kubernetes-sigs/controller-tools 🎉. 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/controller-tools 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]

Hi @AlirezaPourchali. 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.

[AlirezaPourchali]

/kind feature

[AlirezaPourchali]

/area rbac

[k8s-ci-robot]

@AlirezaPourchali: The label(s) area/rbac cannot be applied, because the repository doesn't have them.

Details

In response to this:

/area rbac

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.

[AlirezaPourchali]

/cc @camilamacedo86 @sbueringer @JoelSpeed

[camilamacedo86]

@JoelSpeed @sbueringer WDYT?
If we add roleName could we move forward?
have you better name for the marker?
Maybe only name since it is for rbac one?

[sbueringer]

General idea makes sense to me. I think roleName is fine. Just name doesn't seem clear enough to me. Let's see what @JoelSpeed thinks.

With this it's clear that this rule belongs to the infra-deployment-manager role:

// +kubebuilder:rbac:roleName=infra-deployment-manager,groups=apps,namespace=infrastructure,resources=statefulsets,verbs=get;list

With this it's not really clear what the name is referring to

// +kubebuilder:rbac:name=infra-deployment-manager,groups=apps,namespace=infrastructure,resources=statefulsets,verbs=get;list

(this marker is for a rule, but a rule itself does not have a name)

I realize that namespace is also referring to the Role namespace, but not sure if that's good and we should continue that way

/ok-to-test

[sbueringer]

Re: CI failure (https://prow.k8s.io/view/gs/kubernetes-ci-logs/pr-logs/pull/kubernetes-sigs_controller-tools/1334/pull-controller-tools-test-main/2021884835185823744)

The failure is orthogonal to this PR, looks like our tests are directly downloading envtest/kubebuilder binaries from the old location that is not available anymore. We'll need a PR to migrate this to download from the new location (controller-tools release attachments). I would probably continue to just use curl and not introduce setup-envtest. As part of that we'll also have to download newer binaries (looks like the job is using Kubernetes v1.11, which is not available on the new location)

[JoelSpeed]

I agree, roleName works well here, apart from needing to fix CI separately, I think this LGTM

[sbueringer]

Thx again!

/lgtm
/approve

(We can run retest once CI is fixed on main)

[k8s-ci-robot]

LGTM label has been added.

Details

Git tree hash: 0f32985c89c31a8a5c2cadf923a7e8cfe3c1f51d

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: AlirezaPourchali, sbueringer

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [sbueringer]

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

[sbueringer]

/retest

[camilamacedo86]

Thank you a lot @sbueringer, @JoelSpeed and @AlirezaPourchali 🙏