feat(kustomize/v2): scaffold NamespaceTransformer for multi-namespace RBAC

Scaffold a commented-out NamespaceTransformer configuration as an opt-in
alternative to the "namespace:" field in config/default/kustomization.yaml.

When using namespace-scoped RBAC markers (e.g.
//+kubebuilder:rbac:namespace=infrastructure), the global "namespace:" field
overrides all namespaces, causing ID conflict errors. The NamespaceTransformer
with "unsetOnly: true" preserves explicit namespaces while assigning the
default namespace to resources without one.

Changes:
- Add namespace_transformer.go template scaffolding namespace_transformer.yaml
- Add commented-out [NAMESPACE-TRANSFORMER] section in kustomization.yaml with
  inline documentation explaining the ID conflict issue and opt-in steps
- Add NOTE comment on the "namespace:" field warning about the override behavior
- Register NamespaceTransformer in init.go

Default behavior is completely unchanged. Users who need multi-namespace RBAC
can follow the inline instructions to switch from the "namespace:" field to
the NamespaceTransformer.

Author: AlirezaPourchali

docs/book/src/cronjob-tutorial/testdata/project/config/default/kustomization.yaml

@@ -1,4 +1,9 @@
 # Adds namespace to all resources.
+# NOTE: If you use namespace-scoped RBAC markers (e.g. //+kubebuilder:rbac:namespace=<ns>),
+# the "namespace:" field below will override ALL namespaces — including those explicitly set
+# by your RBAC markers — causing "namespace transformation produces ID conflict" errors.
+# To fix this, comment out the "namespace:" line below and uncomment the [NAMESPACE-TRANSFORMER]
+# section at the bottom of this file. See config/default/namespace_transformer.yaml for details.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -238,3 +243,14 @@ replacements:
 #     fieldPath: .metadata.name
 #   targets: # Do not remove or uncomment the following scaffold marker; required to generate code for target CRD.
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To enable the NamespaceTransformer (e.g. for multi-namespace RBAC),
+# uncomment the "transformers:" section below and comment out the "namespace:" field at the top
+# of this file. This allows resources with explicit namespaces (from RBAC markers like
+# //+kubebuilder:rbac:namespace=<ns>) to keep their namespaces, while resources without an
+# explicit namespace will receive the default project namespace.
+# You will also need to remove "namespace: system" from resource files under config/
+# so that this transformer can assign the default namespace.
+# See config/default/namespace_transformer.yaml for more details.
+#transformers:
+#- namespace_transformer.yaml

docs/book/src/cronjob-tutorial/testdata/project/config/default/namespace_transformer.yaml

@@ -0,0 +1,26 @@
+# This NamespaceTransformer is an alternative to the
+# "namespace:" field in kustomization.yaml.
+# While the "namespace:" field overrides ALL namespaces (potentially breaking multi-namespace setups),
+# this transformer with "unsetOnly: true" only sets namespace on resources that don't already have one.
+#
+# This is useful when using namespace-scoped RBAC markers such as:
+#   //+kubebuilder:rbac:groups=apps,namespace=infrastructure,resources=deployments,verbs=get
+# which generate Roles with explicit namespaces that should be preserved.
+#
+# Usage:
+#   1. Comment out the "namespace:" field in kustomization.yaml
+#   2. Uncomment the "transformers:" section in kustomization.yaml
+#   3. Remove "namespace: system" from any resource files under config/ that should
+#      receive the default namespace from this transformer instead
+#
+# More info: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_namespacetransformer_
+apiVersion: builtin
+kind: NamespaceTransformer
+metadata:
+  name: namespace-transformer
+  namespace: project-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true

docs/book/src/getting-started/testdata/project/config/default/kustomization.yaml

@@ -1,4 +1,9 @@
 # Adds namespace to all resources.
+# NOTE: If you use namespace-scoped RBAC markers (e.g. //+kubebuilder:rbac:namespace=<ns>),
+# the "namespace:" field below will override ALL namespaces — including those explicitly set
+# by your RBAC markers — causing "namespace transformation produces ID conflict" errors.
+# To fix this, comment out the "namespace:" line below and uncomment the [NAMESPACE-TRANSFORMER]
+# section at the bottom of this file. See config/default/namespace_transformer.yaml for details.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -232,3 +237,14 @@ patches:
 #     fieldPath: .metadata.name
 #   targets: # Do not remove or uncomment the following scaffold marker; required to generate code for target CRD.
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To enable the NamespaceTransformer (e.g. for multi-namespace RBAC),
+# uncomment the "transformers:" section below and comment out the "namespace:" field at the top
+# of this file. This allows resources with explicit namespaces (from RBAC markers like
+# //+kubebuilder:rbac:namespace=<ns>) to keep their namespaces, while resources without an
+# explicit namespace will receive the default project namespace.
+# You will also need to remove "namespace: system" from resource files under config/
+# so that this transformer can assign the default namespace.
+# See config/default/namespace_transformer.yaml for more details.
+#transformers:
+#- namespace_transformer.yaml

docs/book/src/getting-started/testdata/project/config/default/namespace_transformer.yaml

@@ -0,0 +1,26 @@
+# This NamespaceTransformer is an alternative to the
+# "namespace:" field in kustomization.yaml.
+# While the "namespace:" field overrides ALL namespaces (potentially breaking multi-namespace setups),
+# this transformer with "unsetOnly: true" only sets namespace on resources that don't already have one.
+#
+# This is useful when using namespace-scoped RBAC markers such as:
+#   //+kubebuilder:rbac:groups=apps,namespace=infrastructure,resources=deployments,verbs=get
+# which generate Roles with explicit namespaces that should be preserved.
+#
+# Usage:
+#   1. Comment out the "namespace:" field in kustomization.yaml
+#   2. Uncomment the "transformers:" section in kustomization.yaml
+#   3. Remove "namespace: system" from any resource files under config/ that should
+#      receive the default namespace from this transformer instead
+#
+# More info: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_namespacetransformer_
+apiVersion: builtin
+kind: NamespaceTransformer
+metadata:
+  name: namespace-transformer
+  namespace: project-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true

docs/book/src/multiversion-tutorial/testdata/project/config/default/kustomization.yaml

@@ -1,4 +1,9 @@
 # Adds namespace to all resources.
+# NOTE: If you use namespace-scoped RBAC markers (e.g. //+kubebuilder:rbac:namespace=<ns>),
+# the "namespace:" field below will override ALL namespaces — including those explicitly set
+# by your RBAC markers — causing "namespace transformation produces ID conflict" errors.
+# To fix this, comment out the "namespace:" line below and uncomment the [NAMESPACE-TRANSFORMER]
+# section at the bottom of this file. See config/default/namespace_transformer.yaml for details.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -256,3 +261,14 @@ replacements:
          index: 1
          create: true
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To enable the NamespaceTransformer (e.g. for multi-namespace RBAC),
+# uncomment the "transformers:" section below and comment out the "namespace:" field at the top
+# of this file. This allows resources with explicit namespaces (from RBAC markers like
+# //+kubebuilder:rbac:namespace=<ns>) to keep their namespaces, while resources without an
+# explicit namespace will receive the default project namespace.
+# You will also need to remove "namespace: system" from resource files under config/
+# so that this transformer can assign the default namespace.
+# See config/default/namespace_transformer.yaml for more details.
+#transformers:
+#- namespace_transformer.yaml

docs/book/src/multiversion-tutorial/testdata/project/config/default/namespace_transformer.yaml

@@ -0,0 +1,26 @@
+# This NamespaceTransformer is an alternative to the
+# "namespace:" field in kustomization.yaml.
+# While the "namespace:" field overrides ALL namespaces (potentially breaking multi-namespace setups),
+# this transformer with "unsetOnly: true" only sets namespace on resources that don't already have one.
+#
+# This is useful when using namespace-scoped RBAC markers such as:
+#   //+kubebuilder:rbac:groups=apps,namespace=infrastructure,resources=deployments,verbs=get
+# which generate Roles with explicit namespaces that should be preserved.
+#
+# Usage:
+#   1. Comment out the "namespace:" field in kustomization.yaml
+#   2. Uncomment the "transformers:" section in kustomization.yaml
+#   3. Remove "namespace: system" from any resource files under config/ that should
+#      receive the default namespace from this transformer instead
+#
+# More info: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_namespacetransformer_
+apiVersion: builtin
+kind: NamespaceTransformer
+metadata:
+  name: namespace-transformer
+  namespace: project-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true

pkg/plugins/common/kustomize/v2/scaffolds/init.go

@@ -67,6 +67,7 @@ func (s *initScaffolder) Scaffold() error {
 	templates := []machinery.Builder{
 		&rbac.Kustomization{},
 		&kdefault.MetricsService{},
+		&kdefault.NamespaceTransformer{},
 		&rbac.MetricsAuthRole{},
 		&rbac.MetricsAuthRoleBinding{},
 		&rbac.MetricsReaderRole{},

pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/kdefault/kustomization.go

@@ -45,6 +45,15 @@ func (f *Kustomization) SetTemplateDefaults() error {
 }
 
 const kustomizeTemplate = `# Adds namespace to all resources.
+# NOTE: If you use namespace-scoped RBAC markers (e.g. //+kubebuilder:rbac:namespace=<ns>),
+# the "namespace:" field below will override ALL namespaces — including those explicitly set
+# by your RBAC markers — causing "namespace transformation produces ID conflict" errors.
+# To fix this:
+#   1. Use the "roleName" parameter in your RBAC markers to give each Role a unique name
+#      (e.g. //+kubebuilder:rbac:namespace=infra,roleName=infra-role,...)
+#   2. Comment out the "namespace:" line below and uncomment the [NAMESPACE-TRANSFORMER]
+#      section at the bottom of this file to preserve explicit namespaces.
+# See config/default/namespace_transformer.yaml for details.
 namespace: {{ .ProjectName }}-system
 
 # Value of this field is prepended to the
@@ -278,4 +287,15 @@ patches:
 #     fieldPath: .metadata.name
 #   targets: # Do not remove or uncomment the following scaffold marker; required to generate code for target CRD.
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To enable the NamespaceTransformer (e.g. for multi-namespace RBAC),
+# uncomment the "transformers:" section below and comment out the "namespace:" field at the top
+# of this file. This allows resources with explicit namespaces (from RBAC markers like
+# //+kubebuilder:rbac:namespace=<ns>) to keep their namespaces, while resources without an
+# explicit namespace will receive the default project namespace.
+# You will also need to remove "namespace: system" from resource files under config/
+# so that this transformer can assign the default namespace.
+# See config/default/namespace_transformer.yaml for more details.
+#transformers:
+#- namespace_transformer.yaml
 `

pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/kdefault/namespace_transformer.go

@@ -0,0 +1,76 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package kdefault
+
+import (
+	"path/filepath"
+
+	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+)
+
+var _ machinery.Template = &NamespaceTransformer{}
+
+// NamespaceTransformer scaffolds a file that defines the NamespaceTransformer
+// for the default overlay folder
+type NamespaceTransformer struct {
+	machinery.TemplateMixin
+	machinery.ProjectNameMixin
+}
+
+// SetTemplateDefaults implements machinery.Template
+func (f *NamespaceTransformer) SetTemplateDefaults() error {
+	if f.Path == "" {
+		f.Path = filepath.Join("config", "default", "namespace_transformer.yaml")
+	}
+
+	f.TemplateBody = namespaceTransformerTemplate
+
+	return nil
+}
+
+const namespaceTransformerTemplate = `# This NamespaceTransformer is an alternative to the
+# "namespace:" field in kustomization.yaml.
+# While the "namespace:" field overrides ALL namespaces (potentially breaking multi-namespace setups),
+# this transformer with "unsetOnly: true" only sets namespace on resources that don't already have one.
+#
+# This is useful when using namespace-scoped RBAC markers such as:
+#   //+kubebuilder:rbac:groups=apps,namespace=infrastructure,resources=deployments,verbs=get
+# which generate Roles with explicit namespaces that should be preserved.
+#
+# TIP: When using multiple namespaces, also consider using the "roleName" parameter
+# in your RBAC markers to give each Role a unique name, e.g.:
+#   //+kubebuilder:rbac:groups=apps,namespace=infrastructure,roleName=infra-role,...
+# This avoids ID conflicts even before switching to the NamespaceTransformer.
+#
+# Usage:
+#   1. Comment out the "namespace:" field in kustomization.yaml
+#   2. Uncomment the "transformers:" section in kustomization.yaml
+#   3. Remove "namespace: system" from any resource files under config/ that should
+#      receive the default namespace from this transformer instead
+#
+# More info: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_namespacetransformer_
+apiVersion: builtin
+kind: NamespaceTransformer
+metadata:
+  name: namespace-transformer
+  namespace: {{ .ProjectName }}-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true
+`