Add support for custom webhook paths

Users can now set custom paths for webhooks using --defaulting-path and
--validation-path flags. Requires controller-runtime v0.20+.

Assisted-by: Cursor

Author: camilamacedo86

docs/book/src/cronjob-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go

@@ -155,6 +155,8 @@ validate anything on deletion.
 /*
 This marker is responsible for generating a validation webhook manifest.
 */
+
+// NOTE: If you want to customise the 'path', use the flags '--defaulting-path' or '--validation-path'.
 // +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob-v1.kb.io,admissionReviewVersions=v1
 
 // CronJobCustomValidator struct is responsible for validating the CronJob resource

docs/book/src/cronjob-tutorial/webhook-implementation.md

@@ -11,12 +11,37 @@ Kubebuilder takes care of the rest for you, such as
 1. Creating handlers for your webhooks.
 1. Registering each handler with a path in your server.
 
-First, let's scaffold the webhooks for our CRD (CronJob). We’ll need to run the following command with the `--defaulting` and `--programmatic-validation` flags (since our test project will use defaulting and validating webhooks):
+First, let's scaffold the webhooks for our CRD (CronJob). We'll need to run the following command with the `--defaulting` and `--programmatic-validation` flags (since our test project will use defaulting and validating webhooks):
 
 ```bash
 kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation
 ```
 
 This will scaffold the webhook functions and register your webhook with the manager in your `main.go` for you.
 
+## Custom Webhook Paths
+
+You can specify custom HTTP paths for your webhooks using the `--defaulting-path` and `--validation-path` flags:
+
+```bash
+# Custom path for defaulting webhook
+kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --defaulting-path=/my-custom-mutate-path
+
+# Custom path for validation webhook
+kubebuilder create webhook --group batch --version v1 --kind CronJob --programmatic-validation --validation-path=/my-custom-validate-path
+
+# Both webhooks with different custom paths
+kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation \
+  --defaulting-path=/custom-mutate --validation-path=/custom-validate
+```
+
+This changes the path in the webhook marker annotation but does not change where the webhook files are scaffolded. The webhook files will still be created in `internal/webhook/v1/`.
+
+<aside class="note">
+<h1>Version Requirements</h1>
+
+Custom webhook paths require **controller-runtime v0.21+**. In earlier versions (< v0.20), the webhook path must follow a specific pattern and cannot be customized. The path is automatically generated based on the resource's group, version, and kind (e.g., `/mutate-batch-v1-cronjob`).
+
+</aside>
+
 {{#literatego ./testdata/project/internal/webhook/v1/cronjob_webhook.go}}

docs/book/src/multiversion-tutorial/conversion.md

@@ -13,6 +13,16 @@ The above command will generate the `cronjob_conversion.go` next to our
 `cronjob_types.go` file, to avoid
 cluttering up our main types file with extra functions.
 
+<aside class="note">
+<h1>Conversion Webhooks and Custom Paths</h1>
+
+Unlike defaulting and validation webhooks, conversion webhooks do not support custom paths
+via command-line flags. Conversion webhooks use CRD conversion configuration
+(`.spec.conversion.webhook.clientConfig.service.path` in the CRD) rather than webhook
+marker annotations. The path for conversion webhooks is managed differently and cannot
+be customized through kubebuilder flags.
+</aside>
+
 ## Hub...
 
 First, we'll implement the hub.  We'll choose the v1 version as the hub:

docs/book/src/multiversion-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go

@@ -160,6 +160,7 @@ validate anything on deletion.
 /*
 This marker is responsible for generating a validation webhook manifest.
 */
+
 // +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob-v1.kb.io,admissionReviewVersions=v1
 
 // CronJobCustomValidator struct is responsible for validating the CronJob resource

docs/book/src/multiversion-tutorial/testdata/project/internal/webhook/v2/cronjob_webhook.go

@@ -88,8 +88,7 @@ func (d *CronJobCustomDefaulter) Default(_ context.Context, obj runtime.Object)
 }
 
 // TODO(user): change verbs to "verbs=create;update;delete" if you want to enable deletion validation.
-// NOTE: The 'path' attribute must follow a specific pattern and should not be modified directly here.
-// Modifying the path for an invalid path can cause API server errors; failing to locate the webhook.
+// NOTE: If you want to customise the 'path', use the flags '--defaulting-path' or '--validation-path'.
 // +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v2-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v2,name=vcronjob-v2.kb.io,admissionReviewVersions=v1
 
 // CronJobCustomValidator struct is responsible for validating the CronJob resource

docs/book/src/reference/admission-webhook.md

@@ -30,6 +30,37 @@ object after your validation has accepted it.
 
 </aside>
 
+## Custom Webhook Paths
+
+By default, Kubebuilder generates webhook paths based on the resource's group, version, and kind. For example:
+- Mutating webhook for `batch/v1/CronJob`: `/mutate-batch-v1-cronjob`
+- Validating webhook for `batch/v1/CronJob`: `/validate-batch-v1-cronjob`
+
+You can specify custom paths for webhooks using dedicated flags:
+
+```bash
+# Custom path for defaulting webhook
+kubebuilder create webhook --group batch --version v1 --kind CronJob \
+  --defaulting --defaulting-path=/my-custom-mutate-path
+
+# Custom path for validation webhook
+kubebuilder create webhook --group batch --version v1 --kind CronJob \
+  --programmatic-validation --validation-path=/my-custom-validate-path
+
+# Both webhooks with different custom paths
+kubebuilder create webhook --group batch --version v1 --kind CronJob \
+  --defaulting --programmatic-validation \
+  --defaulting-path=/custom-mutate --validation-path=/custom-validate
+```
+
+<aside class="note">
+<h1>Version Requirements</h1>
+
+Custom webhook paths require **controller-runtime v0.21+**. In earlier versions (< v0.20), the webhook path follows a
+fixed pattern based on the resource's group, version, and kind, and cannot be customized.
+</aside>
+
+
 ## Handling Resource Status in Admission Webhooks
 
 <aside class="warning">

hack/docs/internal/cronjob-tutorial/generate_cronjob.go

@@ -471,13 +471,12 @@ Then, we set up the webhook with the manager.
 	err = pluginutil.ReplaceInFile(
 		filepath.Join(sp.ctx.Dir, "internal/webhook/v1/cronjob_webhook.go"),
 		`// TODO(user): EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!`, webhooksNoticeMarker)
-	hackutils.CheckError("fixing cronjob_webhook.go by replacing note about path attribute", err)
+	hackutils.CheckError("fixing cronjob_webhook.go by replacing note about path attribute for webhook notice ", err)
 
 	err = pluginutil.ReplaceInFile(
 		filepath.Join(sp.ctx.Dir, "internal/webhook/v1/cronjob_webhook.go"),
-		`// NOTE: The 'path' attribute must follow a specific pattern and should not be modified directly here.
-// Modifying the path for an invalid path can cause API server errors; failing to locate the webhook.`, explanationValidateCRD)
-	hackutils.CheckError("fixing cronjob_webhook.go by replacing note about path attribute", err)
+		`// TODO(user): change verbs to "verbs=create;update;delete" if you want to enable deletion validation.`, explanationValidateCRD)
+	hackutils.CheckError("fixing cronjob_webhook.go by replacing note about path attribute for explanation validate CRD", err)
 
 	err = pluginutil.ReplaceInFile(
 		filepath.Join(sp.ctx.Dir, "internal/webhook/v1/cronjob_webhook.go"),

hack/docs/internal/cronjob-tutorial/webhook_implementation.go

@@ -90,7 +90,9 @@ validate anything on deletion.
 
 /*
 This marker is responsible for generating a validation webhook manifest.
-*/`
+*/
+
+// TODO(user): change verbs to "verbs=create;update;delete" if you want to enable deletion validation.`
 
 const customInterfaceDefaultInfo = `/*
 We use the ` + "`" + `webhook.CustomDefaulter` + "`" + `interface to set defaults to our CRD.

pkg/cli/alpha/internal/generate.go

@@ -459,9 +459,15 @@ func getWebhookResourceFlags(res resource.Resource) []string {
 	}
 	if res.HasValidationWebhook() {
 		args = append(args, "--programmatic-validation")
+		if res.Webhooks.ValidationPath != "" {
+			args = append(args, "--validation-path", res.Webhooks.ValidationPath)
+		}
 	}
 	if res.HasDefaultingWebhook() {
 		args = append(args, "--defaulting")
+		if res.Webhooks.DefaultingPath != "" {
+			args = append(args, "--defaulting-path", res.Webhooks.DefaultingPath)
+		}
 	}
 	if res.HasConversionWebhook() {
 		args = append(args, "--conversion")
@@ -470,6 +476,7 @@ func getWebhookResourceFlags(res resource.Resource) []string {
 				args = append(args, "--spoke", spoke)
 			}
 		}
+		// Note: conversion webhooks don't use custom path flags
 	}
 	return args
 }

pkg/model/resource/webhooks.go

@@ -35,6 +35,14 @@ type Webhooks struct {
 	Conversion bool `json:"conversion,omitempty"`
 
 	Spoke []string `json:"spoke,omitempty"`
+
+	// DefaultingPath holds the custom path for the defaulting/mutating webhook.
+	// This path is used in the +kubebuilder:webhook marker annotation.
+	DefaultingPath string `json:"defaultingPath,omitempty"`
+
+	// ValidationPath holds the custom path for the validation webhook.
+	// This path is used in the +kubebuilder:webhook marker annotation.
+	ValidationPath string `json:"validationPath,omitempty"`
 }
 
 // Validate checks that the Webhooks is valid.
@@ -73,6 +81,8 @@ func (webhooks Webhooks) Copy() Webhooks {
 		Validation:     webhooks.Validation,
 		Conversion:     webhooks.Conversion,
 		Spoke:          spokeCopy,
+		DefaultingPath: webhooks.DefaultingPath,
+		ValidationPath: webhooks.ValidationPath,
 	}
 }
 
@@ -114,14 +124,23 @@ func (webhooks *Webhooks) Update(other *Webhooks) error {
 		}
 	}
 
+	// Update custom paths (other takes precedence if not empty)
+	if other.DefaultingPath != "" {
+		webhooks.DefaultingPath = other.DefaultingPath
+	}
+	if other.ValidationPath != "" {
+		webhooks.ValidationPath = other.ValidationPath
+	}
+
 	return nil
 }
 
 // IsEmpty returns if the Webhooks' fields all contain zero-values.
 func (webhooks Webhooks) IsEmpty() bool {
 	return webhooks.WebhookVersion == "" &&
 		!webhooks.Defaulting && !webhooks.Validation &&
-		!webhooks.Conversion && len(webhooks.Spoke) == 0
+		!webhooks.Conversion && len(webhooks.Spoke) == 0 &&
+		webhooks.DefaultingPath == "" && webhooks.ValidationPath == ""
 }
 
 // AddSpoke adds a new spoke version to the Webhooks configuration.