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

:_mod-docs-content-type: CONCEPT
[id="admission-webhook-types_{context}"]
= Types of webhook admission plugins

[role="_abstract"]
As a cluster administrator, you can call webhook servers through the mutating admission plugin or the validating admission plugin in the API server admission chain.

Mutating admission plugin::
+
The mutating admission plugin is invoked during the mutation phase of the admission process, which allows modification of resource content before it is persisted. One example webhook that can be called through the mutating admission plugin is the Pod Node Selector feature, which uses an annotation on a namespace to find a label selector and add it to the pod specification.
+
.Sample mutating admission plugin configuration
[source,yaml]
----
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
metadata:
  name: <webhook_name>
webhooks:
- name: <webhook_name>
  clientConfig:
    service:
      namespace: default
      name: kubernetes
      path: <webhook_url>
    caBundle: <ca_signing_certificate>
  rules:
  - operations:
    - <operation>
    apiGroups:
    - ""
    apiVersions:
    - "*"
    resources:
    - <resource>
  failurePolicy: <policy>
  sideEffects: None
----
+
--
where:

`kind`:: Specifies a mutating admission plugin configuration.
`metadata.name`:: Specifies the name for the `MutatingWebhookConfiguration` object. Replace `<webhook_name>` with the appropriate value.
`webhooks.name`:: Specifies the name of the webhook to call. Replace `<webhook_name>` with the appropriate value.
`webhooks.clientConfig`:: Specifies information about how to connect to, trust, and send data to the webhook server.
`webhooks.clientConfig.service.namespace`:: Specifies the namespace where the front-end service is created.
`webhooks.clientConfig.service.name`:: Specifies the name of the front-end service.
`webhooks.clientConfig.service.path`:: Specifies the webhook URL used for admission requests. Replace `<webhook_url>` with the appropriate value.
`webhooks.clientConfig.caBundle`:: Specifies a PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `<ca_signing_certificate>` with the appropriate certificate in base64 format.
`webhooks.rules`:: Specifies rules that define when the API server should use this webhook admission plugin.
`webhooks.rules.operations`:: Specifies one or more operations that trigger the API server to call this webhook admission plugin. Possible values are `create`, `update`, `delete`, or `connect`. Replace `<operation>` and `<resource>` with the appropriate values.
`webhooks.failurePolicy`:: Specifies how the policy should proceed if the webhook server is unavailable. Replace `<policy>` with either `Ignore` (to unconditionally accept the request in case of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients.

[IMPORTANT]
====
In {product-title} {product-version}, objects created by users or control loops through a mutating admission plugin might return unexpected results, especially if values set in an initial request are overwritten, which is not recommended.
====
--

Validating admission plugin::
+
A validating admission plugin is invoked during the validation phase of the admission process. This phase allows the enforcement of invariants on particular API resources to ensure that the resource does not change again. The Pod Node Selector is also an example of a webhook which is called by the validating admission plugin, to ensure that all `nodeSelector` fields are constrained by the node selector restrictions on the namespace.
+
.Sample validating admission plugin configuration
[source,yaml]
----
apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
metadata:
  name: <webhook_name>
webhooks:
- name: <webhook_name>
  clientConfig:
    service:
      namespace: default
      name: kubernetes
      path: <webhook_url>
    caBundle: <ca_signing_certificate>
  rules:
  - operations:
    - <operation>
    apiGroups:
    - ""
    apiVersions:
    - "*"
    resources:
    - <resource>
  failurePolicy: <policy>
  sideEffects: Unknown
----
+
--
where:

`kind`:: Specifies a validating admission plugin configuration.
`metadata.name`:: Specifies the name for the `ValidatingWebhookConfiguration` object. Replace `<webhook_name>` with the appropriate value.
`webhooks.name`:: Specifies the name of the webhook to call. Replace `<webhook_name>` with the appropriate value.
`webhooks.clientConfig`:: Specifies information about how to connect to, trust, and send data to the webhook server.
`webhooks.clientConfig.service.namespace`:: Specifies the namespace where the front-end service is created.
`webhooks.clientConfig.service.name`:: Specifies the name of the front-end service.
`webhooks.clientConfig.service.path`:: Specifies the webhook URL used for admission requests. Replace `<webhook_url>` with the appropriate value.
`webhooks.caBundle`:: Specifies a PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `<ca_signing_certificate>` with the appropriate certificate in base64 format.
`webhooks.rules`:: Specifies rules that define when the API server should use this webhook admission plugin.
`webhooks.rules.operations`:: Specifies one or more operations that trigger the API server to call this webhook admission plugin. Possible values are `create`, `update`, `delete`, or `connect`. Replace `<operation>` and `<resource>` with the appropriate values.
`webhooks.failurePolicy`:: Specifies how the policy should proceed if the webhook server is unavailable. Replace `<policy>` with either `Ignore` (to unconditionally accept the request in case of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients.
--
