✨ (kustomize/v2): Add NamespaceTransformer to support multi-namespace…

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

@@ -1,4 +1,5 @@
 # Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -238,3 +239,10 @@ 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 use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml

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

@@ -0,0 +1,39 @@
+# 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,...
+# 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:namespace=infra,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: 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,5 @@
 # Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -232,3 +233,10 @@ 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 use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml

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

@@ -0,0 +1,39 @@
+# 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,...
+# 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:namespace=infra,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: 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,5 @@
 # Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: project-system
 
 # Value of this field is prepended to the
@@ -256,3 +257,10 @@ replacements:
          index: 1
          create: true
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml

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

@@ -0,0 +1,39 @@
+# 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,...
+# 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:namespace=infra,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: 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,7 @@ func (f *Kustomization) SetTemplateDefaults() error {
 }
 
 const kustomizeTemplate = `# Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: {{ .ProjectName }}-system
 
 # Value of this field is prepended to the
@@ -278,4 +279,11 @@ 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 use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml
 `

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

@@ -0,0 +1,84 @@
+/*
+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,...
+# 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:namespace=infra,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
+`

testdata/project-v4-multigroup/config/default/kustomization.yaml

@@ -1,4 +1,5 @@
 # Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: project-v4-multigroup-system
 
 # Value of this field is prepended to the
@@ -250,3 +251,10 @@ replacements:
          index: 1
          create: true
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml

testdata/project-v4-multigroup/config/default/namespace_transformer.yaml

@@ -0,0 +1,39 @@
+# 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,...
+# 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:namespace=infra,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: project-v4-multigroup-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true

testdata/project-v4-with-plugins/config/default/kustomization.yaml

@@ -1,4 +1,5 @@
 # Adds namespace to all resources.
+# If using namespace-scoped RBAC, see [NAMESPACE-TRANSFORMER] below.
 namespace: project-v4-with-plugins-system
 
 # Value of this field is prepended to the
@@ -250,3 +251,10 @@ replacements:
          index: 1
          create: true
 # +kubebuilder:scaffold:crdkustomizecainjectionname
+
+# [NAMESPACE-TRANSFORMER] To use the NamespaceTransformer instead of the
+# "namespace:" field (e.g. for multi-namespace RBAC), comment out "namespace:"
+# above and uncomment the transformers section below.
+# See config/default/namespace_transformer.yaml for details.
+#transformers:
+#- namespace_transformer.yaml

testdata/project-v4-with-plugins/config/default/namespace_transformer.yaml

@@ -0,0 +1,39 @@
+# 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,...
+# 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:namespace=infra,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: project-v4-with-plugins-system
+setRoleBindingSubjects: allServiceAccounts
+unsetOnly: true
+fieldSpecs:
+  - path: metadata/namespace
+    create: true