✨ (go/v4): Add --namespaced flag for namespace-scoped managers

[camilamacedo86]

Add --namespaced flag to scaffold managers that watch only specific namespace(s),
enabling least-privilege deployments and multi-tenant architectures.

Moreover, fix and supplement the documentation accordingly.

Closes: #2123

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86

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 [camilamacedo86]

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

[Copilot]

Pull request overview

This pull request adds namespace-scoped deployment support to Kubebuilder, allowing operators to be configured to watch and manage resources in specific namespace(s) rather than cluster-wide. This addresses issue #2123 by providing a --namespaced flag (similar to the existing --multigroup flag) for both init and edit commands.

Changes:

• Added --namespaced flag to kubebuilder init and kubebuilder edit commands for scaffolding namespace-scoped operators
• Implemented namespace-scoped RBAC generation (Role/RoleBinding instead of ClusterRole/ClusterRoleBinding)
• Added namespace watching configuration in main.go template with support for single and multi-namespace modes via WATCH_NAMESPACE environment variable
• Added comprehensive documentation including migration guide, manager scope reference, and CRD scope reference

Reviewed changes

Copilot reviewed 58 out of 71 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pkg/config/interface.go	Added IsNamespaced(), SetNamespaced(), and ClearNamespaced() interface methods
pkg/config/v3/config.go	Implemented namespaced flag in config struct and methods
pkg/machinery/interfaces.go	Added HasNamespaced interface for templates
pkg/machinery/injector.go	Added injection of namespaced flag to templates
pkg/machinery/mixins.go	Added NamespacedMixin for template scaffolding
pkg/plugins/golang/v4/init.go	Added --namespaced flag to init command
pkg/plugins/golang/v4/edit.go	Added --namespaced flag to edit command
pkg/plugins/golang/v4/scaffolds/edit.go	Added RBAC scaffolding logic for namespace-scoped mode
pkg/plugins/golang/v4/scaffolds/internal/templates/cmd/main.go	Added conditional scaffolding for namespace watching code
pkg/plugins/golang/v4/scaffolds/internal/templates/controllers/controller.go	Added conditional RBAC markers with namespace parameter
pkg/plugins/golang/deploy-image/v1alpha1/scaffolds/internal/templates/controllers/controller.go	Added namespace-scoped RBAC marker support
pkg/plugins/common/kustomize/v2/scaffolds/init.go	Added conditional scaffolding of Role vs ClusterRole based on namespaced flag
pkg/plugins/common/kustomize/v2/scaffolds/edit.go	Added edit scaffolder for toggling RBAC between namespaced and cluster-scoped
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/rbac/namespaced_role.go	New template for namespace-scoped Role
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/rbac/namespaced_role_binding.go	New template for namespace-scoped RoleBinding
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/rbac/cluster_role.go	Renamed from Role to ClusterRole for clarity
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/rbac/cluster_role_binding.go	Renamed from RoleBinding to ClusterRoleBinding for clarity
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/rbac/crd_*_role.go	Added conditional Kind (Role vs ClusterRole) based on namespaced flag
pkg/plugins/common/kustomize/v2/scaffolds/internal/templates/config/manager/config.go	Added conditional WATCH_NAMESPACE environment variable
pkg/plugins/optional/helm/v2alpha/scaffolds/internal/kustomize/helm_templater.go	Added roleRef name substitution for Helm charts
test/e2e/v4/plugin_cluster_test.go	Added namespace-scoped e2e tests with namespace isolation verification
test/e2e/v4/generate_test.go	Added GenerateV4Namespaced and GenerateV4NamespacedWithoutWebhooks test functions
test/testdata/generate.sh	Updated to scaffold project-v4-with-plugins with --namespaced flag
testdata/project-v4-with-plugins/*	Regenerated test data with namespace-scoped configuration
docs/book/src/reference/scopes.md	Restructured to explain manager vs CRD scope concepts
docs/book/src/reference/manager-scope.md	New comprehensive manager scope reference documentation
docs/book/src/reference/crd-scope.md	New comprehensive CRD scope reference documentation
docs/book/src/migration/namespace-scoped.md	New migration guide for converting existing projects to namespace-scoped
docs/book/src/SUMMARY.md	Added new documentation pages to book navigation
**/AGENTS.md	Added namespace-scoped conversion instructions for AI agents

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[camilamacedo86]

/retest-required

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-33-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-34-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-34-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-34-0

[camilamacedo86]

/test pull-kubebuilder-e2e-k8s-1-34-0

[k8s-ci-robot]

@camilamacedo86: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-kubebuilder-e2e-k8s-1-34-0	f95dc0a	link	true	/test pull-kubebuilder-e2e-k8s-1-34-0

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

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.