Merge pull request #5482 from camilamacedo86/namespaced-webhook

✨ (go/v4): Add webhook scope mismatch warning for namespace-scoped mode

Author: k8s-ci-robot

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

@@ -270,6 +270,24 @@ kubectl apply -f config/samples/ -n <manager-namespace>
 kubectl apply -f config/samples/ -n other-namespace
 ```
 
+<aside class="warning">
+
+<h1>Webhooks and Namespace-Scoped Mode</h1>
+
+If your project has webhooks, the manager cache is restricted to `WATCH_NAMESPACE`, but webhooks receive requests from all namespaces by default.
+
+**The Problem:**
+
+Your webhook server receives admission requests from all namespaces, but the cache only has data from `WATCH_NAMESPACE`. If a webhook handler queries the cache for an object outside the watched namespaces, the lookup fails.
+
+**Solution:**
+
+Configure `namespaceSelector` or `objectSelector` on your webhooks to align webhook scope with the cache. Currently, controller-gen does not have markers for this. You must add these manually using Kustomize patches.
+
+See the [Webhook Bootstrap Problem](../reference/webhook-bootstrap-problem.html) guide for detailed steps on creating and applying namespace selector patches.
+
+</aside>
+
 ## AI-Assisted Migration
 
 If you're using an AI coding assistant (Cursor, GitHub Copilot, etc.), you can automate the manual migration steps.
@@ -486,11 +504,11 @@ This command automatically:
 ## Important Notes
 
 - **Only controllers need RBAC updates**: Only update `+kubebuilder:rbac` markers in controller files (files with `Reconcile` function). Webhook files do NOT use RBAC markers - webhooks use certificate-based authentication with the API server.
-- **Webhooks remain cluster-scoped**: `ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration` are cluster-scoped resources that validate/mutate CRs in all namespaces. This is correct - webhooks enforce schema consistency across the cluster, while controllers (namespace-scoped) only reconcile resources in their watched namespace(s).
 - **RBAC markers control scope**: The `namespace=` parameter in controller RBAC markers determines whether controller-gen generates `Role` (namespace-scoped) or `ClusterRole` (cluster-scoped). Without the `namespace=` parameter, controller-gen always generates `ClusterRole`.
 - **Controller-gen regenerates role.yaml**: After running `make manifests`, controller-gen will regenerate `config/rbac/role.yaml` based on your controller RBAC markers. The initial `Role` scaffold from `kubebuilder edit --namespaced=true` serves as a template, but controller-gen manages the actual content.
 - **Namespace parameter format**: Use `namespace=<your-namespace>` in controller RBAC markers, typically `namespace=<project-name>-system` to match your deployment namespace.
 - **Metrics auth role stays cluster-scoped**: The `metrics-auth-role` uses cluster-scoped APIs (TokenReview, SubjectAccessReview) and correctly remains a ClusterRole without namespace parameter.
+- **Webhooks require manual configuration**: Currently, controller-gen does not support `namespaceSelector` or `objectSelector` markers for webhooks. See the webhook section above for details.
 
 ## See Also
 

docs/book/src/reference/manager-scope.md

@@ -145,6 +145,24 @@ The `testdata/project-v4-with-plugins` in the Kubebuilder repository demonstrate
 See: [testdata/project-v4-with-plugins](https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins)
 </aside>
 
+<aside class="warning">
+
+<h1>Webhooks and Namespace-Scoped Mode</h1>
+
+If your project has webhooks, the manager cache is restricted to `WATCH_NAMESPACE`, but webhooks receive requests from all namespaces by default.
+
+**The Problem:**
+
+Your webhook server receives admission requests from all namespaces, but the cache only has data from `WATCH_NAMESPACE`. If a webhook handler queries the cache for an object outside the watched namespaces, the lookup fails.
+
+**Solution:**
+
+Configure `namespaceSelector` or `objectSelector` on your webhooks to align webhook scope with the cache. Currently, controller-gen does not have markers for this. You must add these manually using Kustomize patches.
+
+See the [Webhook Bootstrap Problem](../reference/webhook-bootstrap-problem.html) guide for detailed steps on creating and applying namespace selector patches.
+
+</aside>
+
 ## See Also
 
 - [Understanding Scopes](./scopes.md) - Overview of manager and CRD scopes

pkg/plugins/golang/v4/edit.go

@@ -48,14 +48,21 @@ Multigroup (--multigroup):
   Changes API structure: api/<version>/ becomes api/<group>/<version>/
   Automatic: Updates PROJECT file, future APIs use new structure
   Manual: Move existing API files, update import paths in controllers
-  Migration guide: https://book.kubebuilder.io/migration/multi-group.html
+  More info: https://book.kubebuilder.io/migration/multi-group.html
 
 Namespaced (--namespaced):
   Enable or disable namespace-scoped deployment.
   Manager watches one or more specific namespaces vs all namespaces.
   Namespaces to watch are configured via WATCH_NAMESPACE environment variable.
   Automatic: Updates PROJECT file, scaffolds Role/RoleBinding, uses --force to regenerate manager.yaml
   Manual: Add namespace= to RBAC markers in existing controllers, update cmd/main.go, run 'make manifests'
+  More info: https://book.kubebuilder.io/migration/namespace-scoped.html 
+  
+  WARNING - Webhooks and Namespace-Scoped Mode:
+  Webhooks remain cluster-scoped even in namespace-scoped mode.
+  The manager cache is restricted to WATCH_NAMESPACE, but webhooks receive requests
+  from ALL namespaces. You must configure namespaceSelector or objectSelector to align
+  webhook scope with the cache.
 
 Force (--force):
   Overwrite existing scaffolded files to apply configuration changes.

pkg/plugins/golang/v4/scaffolds/edit.go

@@ -18,6 +18,7 @@ package scaffolds
 
 import (
 	"fmt"
+	log "log/slog"
 
 	"github.com/spf13/afero"
 
@@ -91,6 +92,12 @@ func (s *editScaffolder) Scaffold() error {
 			fmt.Println("Run with --force to update config/manager/manager.yaml with WATCH_NAMESPACE")
 		}
 
+		// Check if project has webhooks and warn about scope mismatch
+		if s.hasWebhooks() {
+			log.Warn("your project has webhooks which are cluster-scoped.\n" +
+				"You will need to manually configure namespaceSelector or objectSelector")
+		}
+
 		// Print next steps
 		fmt.Println()
 		fmt.Println("Next steps:")
@@ -99,6 +106,11 @@ func (s *editScaffolder) Scaffold() error {
 		fmt.Printf("   // +kubebuilder:rbac:groups=mygroup,resources=myresources,verbs=get;list,"+
 			"namespace=%s-system\n", s.config.GetProjectName())
 		fmt.Println("3. Run: make manifests")
+
+		if s.hasWebhooks() {
+			fmt.Println("4. Configure namespaceSelector or objectSelector for webhooks")
+		}
+
 		fmt.Println()
 		fmt.Println("See: https://book.kubebuilder.io/migration/namespace-scoped.html")
 	} else if !s.namespaced && wasNamespaced {
@@ -155,3 +167,17 @@ func (s *editScaffolder) scaffoldClusterRBAC(force bool) error {
 	}
 	return nil
 }
+
+// hasWebhooks checks if any resources in the project have webhooks configured
+func (s *editScaffolder) hasWebhooks() bool {
+	resources, err := s.config.GetResources()
+	if err != nil {
+		return false
+	}
+	for _, res := range resources {
+		if res.Webhooks != nil && !res.Webhooks.IsEmpty() {
+			return true
+		}
+	}
+	return false
+}