chore(CLI): Add option for namespaced layout such as we have for multigroup

Author: camilamacedo86

docs/book/src/SUMMARY.md

@@ -53,6 +53,7 @@
       - [Step 2: Discovery Commands](./migration/discovery-commands.md)
       - [Step 3: Port Code](./migration/port-code.md)
   - [Single Group to Multi-Group](./migration/multi-group.md)
+  - [Cluster-Scoped to Namespace-Scoped](./migration/namespace-scoped.md)
 
 - [Alpha Commands](./reference/alpha_commands.md)
 
@@ -92,6 +93,8 @@
   - [Monitoring with Pprof](./reference/pprof-tutorial.md)
 
   - [Manager and CRDs Scope](./reference/scopes.md)
+    - [Operator Scope](./reference/operator-scope.md)
+    - [CRD Scope](./reference/crd-scope.md)
 
   - [Sub-Module Layouts](./reference/submodule-layouts.md)
   - [Using an external Resource / API](./reference/using_an_external_resource.md)

docs/book/src/migration/namespace-scoped.md

@@ -0,0 +1,173 @@
+# Migrating to Namespace-Scoped Operator
+
+By default, Kubebuilder scaffolds cluster-scoped operators that watch and manage resources across all namespaces. You can convert an existing project to namespace-scoped deployment, limiting the operator to watch only specific namespace(s).
+
+## When to Use Namespace-Scoped
+
+**Use namespace-scoped when:**
+- Building tenant-specific operators in multi-tenant clusters
+- Security policies require least-privilege (no cluster-wide permissions)
+- Need multiple operator instances in different namespaces
+- Managing only namespace-scoped resources (Deployments, Services, ConfigMaps, etc.)
+
+**Use cluster-scoped (default) when:**
+- Managing cluster-scoped resources (Nodes, ClusterRoles, Namespaces, etc.)
+- Single operator instance managing resources across all namespaces
+
+## Migration Steps
+
+### 1. Enable namespace-scoped mode
+
+```bash
+kubebuilder edit --namespaced=true
+```
+
+This command:
+- Sets `namespaced: true` in your PROJECT file
+- Scaffolds RBAC patch files to convert ClusterRole/ClusterRoleBinding to Role/RoleBinding
+- Updates `config/rbac/kustomization.yaml` to apply patches
+- Updates `config/manager/manager.yaml` to include `WATCH_NAMESPACE` environment variable
+
+<aside class="warning">
+<h1>Manual Step Required</h1>
+
+The `edit` command cannot automatically update `cmd/main.go`. You must manually add the namespace watching logic.
+</aside>
+
+### 2. Update cmd/main.go (Required Manual Step)
+
+The operator needs to read the `WATCH_NAMESPACE` environment variable to determine which namespace(s) to watch. Add the following changes to `cmd/main.go`:
+
+**Add imports:**
+```go
+import (
+    // ... existing imports ...
+    "fmt"
+    "strings"
+    "sigs.k8s.io/controller-runtime/pkg/cache"
+)
+```
+
+**Add helper function after `init()` and before `main()`:**
+```go
+// getWatchNamespace returns the namespace(s) the operator should watch.
+func getWatchNamespace() (string, error) {
+    watchNamespaceEnvVar := "WATCH_NAMESPACE"
+    ns, found := os.LookupEnv(watchNamespaceEnvVar)
+    if !found {
+        return "", fmt.Errorf("%s must be set", watchNamespaceEnvVar)
+    }
+    return ns, nil
+}
+```
+
+**In `main()` function, add namespace retrieval before creating the manager:**
+```go
+func main() {
+    // ... existing flag parsing and setup ...
+
+    ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))
+
+    // Get the namespace(s) to watch from WATCH_NAMESPACE environment variable
+    watchNamespace, err := getWatchNamespace()
+    if err != nil {
+        setupLog.Error(err, "Unable to get WATCH_NAMESPACE")
+        os.Exit(1)
+    }
+
+    // ... continue with manager creation ...
+}
+```
+
+**Update manager creation to configure namespace watching:**
+```go
+mgrOptions := ctrl.Options{
+    Scheme:                 scheme,
+    Metrics:                metricsServerOptions,
+    WebhookServer:          webhookServer,
+    HealthProbeBindAddress: probeAddr,
+    LeaderElection:         enableLeaderElection,
+}
+
+// Configure cache based on WATCH_NAMESPACE
+if strings.Contains(watchNamespace, ",") {
+    // Multi-namespace mode: watch multiple specific namespaces
+    setupLog.Info("Manager configured for multi-namespace mode", "namespaces", watchNamespace)
+    mgrOptions.NewCache = cache.MultiNamespacedCacheBuilder(strings.Split(watchNamespace, ","))
+} else {
+    // Single namespace mode: watch only one specific namespace
+    setupLog.Info("Manager configured for namespace-scoped mode", "namespace", watchNamespace)
+    mgrOptions.Cache = cache.Options{
+        DefaultNamespaces: map[string]cache.Config{
+            watchNamespace: {},
+        },
+    }
+}
+
+mgrOptions.LeaderElectionID = "your-leader-election-id"
+
+mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), mgrOptions)
+if err != nil {
+    setupLog.Error(err, "Failed to start manager")
+    os.Exit(1)
+}
+```
+
+### 3. Verify the migration
+
+```bash
+make manifests      # Regenerate CRDs and RBAC
+make generate       # Regenerate code
+make test           # Run tests
+```
+
+### 4. Deploy and test
+
+```bash
+make deploy IMG=<your-image>
+
+# Verify RBAC is namespace-scoped (not cluster-scoped)
+kubectl get role,rolebinding -n <operator-namespace>
+
+# Test: Create a resource in the operator's namespace - should be reconciled
+kubectl apply -f config/samples/ -n <operator-namespace>
+
+# Test: Create a resource in a different namespace - should NOT be reconciled
+kubectl apply -f config/samples/ -n other-namespace
+```
+
+## Multi-Namespace Support
+
+The `WATCH_NAMESPACE` environment variable supports comma-separated values to watch multiple specific namespaces:
+
+```yaml
+env:
+- name: WATCH_NAMESPACE
+  value: "namespace-1,namespace-2,namespace-3"
+```
+
+Note: You'll need to create Role/RoleBinding in each namespace for proper RBAC.
+
+## Reverting to Cluster-Scoped
+
+To revert:
+
+```bash
+kubebuilder edit --namespaced=false
+```
+
+Then manually remove the namespace-scoped code from `cmd/main.go`:
+- Remove the `getWatchNamespace()` function
+- Remove the namespace retrieval and cache configuration
+- Remove the added imports (`fmt`, `strings`, `cache`) if not used elsewhere
+
+## Important Notes
+
+- **RBAC markers unchanged**: Your controller RBAC markers (`+kubebuilder:rbac`) remain the same. The scope is determined by deployment configuration (Role vs ClusterRole).
+- **Controller-gen always generates ClusterRole**: This is normal. Kustomize patches convert it to Role at deployment time.
+- **Metrics auth role stays cluster-scoped**: The `metrics-auth-role` uses cluster-scoped APIs (TokenReview, SubjectAccessReview) and correctly remains a ClusterRole.
+
+## See Also
+
+- [Operator Scope](../reference/operator-scope.md) - Detailed explanation of operator scope concepts
+- [Project Config](../reference/project-config.md) - PROJECT file configuration reference