Webhook
These markers describe how webhook configuration is generated. Use these to keep the description of your webhooks close to the code that implements them.
- // +kubebuilder:webhookconfiguration
-
- mutating
- bool
- name
- string
specifies how a webhook should be served.
It specifies only the details that are intrinsic to the application serving it (e.g. the resources it can handle, or the path it serves on).
Example (Validating Webhook):
// +kubebuilder:webhook:path=/validate-mygroup-v1-myresource,mutating=false,failurePolicy=fail,sideEffects=None,groups=mygroup.example.com,resources=myresources,verbs=create;update,versions=v1,name=myresource.kb.io,admissionReviewVersions=v1Example (Mutating Webhook):
// +kubebuilder:webhook:path=/mutate-mygroup-v1-myresource,mutating=true,failurePolicy=fail,sideEffects=None,groups=mygroup.example.com,resources=myresources,verbs=create;update,versions=v1,name=myresource.kb.io,admissionReviewVersions=v1- mutating
- bool
marks this as a mutating webhook (it's validating only if false)
Mutating webhooks are allowed to change the object in their response, and are called before all validating webhooks. Mutating webhooks may choose to reject an object, similarly to a validating webhook.
- name
- string
indicates the name of this webhook configuration. Should be a domain with at least three segments separated by dots
Example: "myresource.mygroup.example.com".
- // +kubebuilder:webhook
-
- admissionReviewVersions
- string
- failurePolicy
- string
- groups
- string
- matchPolicy
- string
- mutating
- bool
- name
- string
- path
- string
- reinvocationPolicy
- string
- resources
- string
- serviceName
- string
- serviceNamespace
- string
- servicePort
- int
- sideEffects
- string
- timeoutSeconds
- int
- url
- string
- verbs
- string
- versions
- string
- webhookVersions
- string
specifies how a webhook should be served.
It specifies only the details that are intrinsic to the application serving it (e.g. the resources it can handle, or the path it serves on).
Example (Validating Webhook):
// +kubebuilder:webhook:path=/validate-mygroup-v1-myresource,mutating=false,failurePolicy=fail,sideEffects=None,groups=mygroup.example.com,resources=myresources,verbs=create;update,versions=v1,name=myresource.kb.io,admissionReviewVersions=v1Example (Mutating Webhook):
// +kubebuilder:webhook:path=/mutate-mygroup-v1-myresource,mutating=true,failurePolicy=fail,sideEffects=None,groups=mygroup.example.com,resources=myresources,verbs=create;update,versions=v1,name=myresource.kb.io,admissionReviewVersions=v1- admissionReviewVersions
- string
is an ordered list of preferred `AdmissionReview`
versions the Webhook expects. The API server will try to use the first version in the list which it supports. If none of the versions specified are supported, the API call will fail. Common values: "v1" or "v1;v1beta1".
- failurePolicy
- string
specifies what should happen if the API server cannot reach the webhook.
It may be either "ignore" (to skip the webhook and continue on) or "fail" (to reject the object in question). Most webhooks should use "fail" to ensure the webhook logic is always executed.
- groups
- string
specifies the API groups that this webhook receives requests for.
Use "" to match all groups. Multiple groups are separated by semicolons. Example: "apps;batch" or "".
- matchPolicy
- string
defines how the "rules" list is used to match incoming requests.
Allowed values are "Exact" (match only if it exactly matches the specified rule) or "Equivalent" (match a request if it modifies a resource listed in rules, even via another API group or version). Defaults to "Equivalent" if not specified.
- mutating
- bool
marks this as a mutating webhook (it's validating only if false)
Mutating webhooks are allowed to change the object in their response, and are called before all validating webhooks. Mutating webhooks may choose to reject an object, similarly to a validating webhook.
- name
- string
indicates the name of this webhook configuration. Should be a domain with at least three segments separated by dots
Example: "myresource.mygroup.example.com".
- path
- string
specifies that path that the API server should connect to this webhook on. Must be
prefixed with a '/validate-' or '/mutate-' depending on the type, and followed by $GROUP-$VERSION-$KIND where all values are lower-cased and the periods in the group are substituted for hyphens. For example, a validating webhook path for type batch.tutorial.kubebuilder.io/v1,Kind=CronJob would be /validate-batch-tutorial-kubebuilder-io-v1-cronjob
- reinvocationPolicy
- string
allows mutating webhooks to request reinvocation after other mutations.
To allow mutating admission plugins to observe changes made by other plugins, built-in mutating admission plugins are re-run if a mutating webhook modifies an object, and mutating webhooks can specify a reinvocationPolicy to control whether they are reinvoked as well. May be "Never" or "IfNeeded". Defaults to "Never".
- resources
- string
specifies the API resources that this webhook receives requests for.
Use "" to match all resources. Multiple resources are separated by semicolons. Example: "deployments;pods" or "".
- serviceName
- string
indicates the name of the K8s Service the webhook uses.
Defaults to "webhook-service" if not specified.
- serviceNamespace
- string
indicates the namespace of the K8s Service the webhook uses.
Defaults to "system" if not specified.
- servicePort
- int
indicates the port of the K8s Service the webhook uses.
Defaults to 443 if not specified.
- sideEffects
- string
specify whether calling the webhook will have side effects.
This has an impact on dry runs and
kubectl diff: if the sideEffect is "Unknown" (the default) or "Some", then the API server will not call the webhook on a dry-run request and fails instead. If the value is "None", then the webhook has no side effects and the API server will call it on dry-run. If the value is "NoneOnDryRun", then the webhook is responsible for inspecting the "dryRun" property of the AdmissionReview sent in the request, and avoiding side effects if that value is "true." Most webhooks should use "None".- timeoutSeconds
- int
allows configuring how long the API server should wait for a webhook to respond before treating the call as a failure.
If the timeout expires before the webhook responds, the webhook call will be ignored or the API call will be rejected based on the failure policy. The timeout value must be between 1 and 30 seconds. The timeout for an admission webhook defaults to 10 seconds.
- url
- string
allows mutating webhooks configuration to specify an external URL when generating
the manifests, instead of using the internal service communication. Should be in format of https://address:port/path When this option is specified, the serviceConfig.Service is removed from webhook the manifest. The URL configuration should be between quotes.
urlcannot be specified whenpathis specified.- verbs
- string
specifies the Kubernetes API verbs that this webhook receives requests for.
Only modification-like verbs may be specified. May be "create", "update", "delete", "connect", or "*" (for all). Multiple verbs are separated by semicolons. Example: "create;update".
- versions
- string
specifies the API versions that this webhook receives requests for.
Use "" to match all versions. Multiple versions are separated by semicolons. Example: "v1;v1beta1" or "".
- webhookVersions
- string
specifies the target API versions of the {Mutating,Validating}WebhookConfiguration objects
itself to generate. The only supported value is v1. Defaults to v1.