// Module included in the following assemblies:
//
// * architecture/admission-plug-ins.adoc

:_mod-docs-content-type: CONCEPT
[id="admission-webhooks-about_{context}"]
= Webhook admission plugins

[role="_abstract"]
In addition to {product-title} default admission plugins, you can implement dynamic admission through webhook admission plugins that call webhook servers. This approach extends the functionality of the admission chain.

Webhook servers are called over HTTP at defined endpoints.

There are two types of webhook admission plugins in {product-title}:

//Future xref - * During the admission process, xref:../architecture/admission-plug-ins.adoc#mutating-admission-plug-in[the mutating admission plugin] can perform tasks, such as injecting affinity labels.

* During the admission process, the _mutating admission plugin_ can perform tasks, such as injecting affinity labels.

//Future xref - * At the end of the admission process, xref:../architecture/admission-plug-ins.adoc#validating-admission-plug-in[the validating admission plugin] makes sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured.

* At the end of the admission process, the _validating admission plugin_ validates that an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured.

When an API request comes in, mutating or validating admission plugins use the list of external webhooks in the configuration and call them in parallel:

* If all of the webhooks approve the request, the admission chain continues.

* If any of the webhooks deny the request, the admission request is denied and the reason for doing so is based on the first denial.

* If more than one webhook denies the admission request, only the first denial reason is returned to the user.

* If an error is encountered when calling a webhook, the request is either denied or the webhook is ignored depending on the error policy set.
If the error policy is set to `Ignore`, the request is unconditionally accepted in the event of a failure.
If the policy is set to `Fail`, failed requests are denied.
Using `Ignore` can result in unpredictable behavior for all clients.

ifndef::openshift-rosa,openshift-dedicated[]
//Future xrefs - Communication between the webhook admission plugin and the webhook server must use TLS. Generate a certificate authority (CA) certificate and use the certificate to sign the server certificate that is used by your webhook server. The PEM-encoded CA certificate is supplied to the webhook admission plugin using a mechanism, such as xref:../security/certificates/service-serving-certificate.adoc#service-serving-certificate[service serving certificate secrets].
Communication between the webhook admission plugin and the webhook server must use TLS. Generate a CA certificate and use the certificate to sign the server certificate that is used by your webhook admission server. The PEM-encoded CA certificate is supplied to the webhook admission plugin using a mechanism, such as service serving certificate secrets.
endif::openshift-rosa,openshift-dedicated[]

The following diagram illustrates the sequential admission chain process within which multiple webhook servers are called.

.API admission chain with mutating and validating admission plugins
image::api-admission-chain.png["API admission stage", align="center"]

An example webhook admission plugin use case is where all pods must have a common set of labels. In this example, the mutating admission plugin can inject labels and the validating admission plugin can check that labels are as expected. {product-title} would subsequently schedule pods that include required labels and reject those that do not.

Some common webhook admission plugin use cases include:

//Future xref - * Namespace reservation.
* Namespace reservation.
//Future xrefs - * :../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Limiting custom network resources managed by the SR-IOV network device plugin].
* Limiting custom network resources managed by the SR-IOV network device plugin.
ifndef::openshift-rosa,openshift-dedicated[]
//Future xref - * xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations_dedicating_nodes-scheduler-taints-tolerations[Defining tolerations that enable taints to qualify which pods should be scheduled on a node].
* Defining tolerations that enable taints to qualify which pods should be scheduled on a node.
//Future xref - * xref:../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-names_nodes-pods-priority[Pod priority class validation].
endif::openshift-rosa,openshift-dedicated[]
* Pod priority class validation.

[NOTE]
====
The maximum default webhook timeout value in {product-title} is 13 seconds, and it cannot be changed.
====
