Add Admission Webhook Document

content/en/docs/Reference/admission-webhooks.md

@@ -0,0 +1,15 @@
+---
+title: "Admission Webhook Reference"
+linkTitle: "Admission Webhook Reference"
+weight: 3
+date: 2020-04-24
+---
+
+After a request has been authenticated and authorized, admission webhooks intercept requests against the Kubernetes API and have an opportunity to validate or update the object before it is saved in the object store. Please refer to the following table that highlights what each webhook is capable of:
+
+|                    | Validating Webhooks | Mutating Webhooks |
+|--------------------|---------------------|-------------------|
+| Validating Objects |          x          |         x         |
+| Mutating Objects   |                     |         x         |
+
+If you are interested in learning more about admission webhooks, please review the [official kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#what-are-they).

content/en/docs/advanced-tasks/adding-an-admission-webhook.md

@@ -0,0 +1,72 @@
+---
+title: "Shipping an operator that includes Admission Webhooks"
+linkTitle: "Admission Webhooks"
+weight: 3
+---
+
+## Defining your Webhook in the ClusterServiceVersion
+
+OLM is capable of managing the lifecycle of [validating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) and [mutating](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) admission webhooks that are shipped alongside your operator.  To this end, the [ClusterServiceVersion resource](/docs/Concepts/crds/clusterserviceversion) includes a [WebhookDefinition object](https://github.com/operator-framework/api/blob/7856a40f92893fe94d19d223f5277d1d116ffc67/pkg/operators/v1alpha1/clusterserviceversion_types.go#L164-L180) which can be used to define validating and mutating admission webhooks that will be shipped with the operator. For your convenience, an example of a Validating WebhookDefinition can be seen below:
+
+```yaml
+apiVersion: operators.coreos.com/v1alpha1
+kind: ClusterServiceVersion
+metadata:
+  annotations:
+    description: |-
+      An example CSV that contains a webhook
+  name: example-webhook.v1.0.0
+  namespace: placeholder
+spec:
+  webhookdefinitions:
+  - generateName: example.webhook.com
+    type: ValidatingAdmissionWebhook
+    deploymentName: "example-webhook-deployment"
+    containerPort: 443
+    sideEffects: "None"
+    failurePolicy: "Ignore"
+    admissionReviewVersions:
+    - "v1"
+    - "v1beta1"
+    rules:
+    - operations:
+      - "CREATE"
+      apiGroups:
+      - ""
+      apiVersions:
+      - "v1"
+      resources:
+      - "configmaps"
+    objectSelector:
+      foo: bar
+    webhookPath: "/validate"
+...
+...
+...
+```
+
+The `WebhookDescription` object contains a union of the fields defined in the AdmissionWebhook and ValidatingWebhook Kubernetes objects with the exception of the NamespaceSelector, which is generated by OLM to match namespaces scoped by the [OperatorGroup](./operator-scoping.md) that the operator is deployed in.
+
+OLM requires that you define the following:
+
+- The `Type` field must be set to `ValidatingAdmissionWebhook` or `MutatingAdmissionWebhook` or the CSV will be placed in the failed phase.
+- The CSV must contain a Deployment whose name is equivalent to the value supplied in the `DeploymentName` field of the `WebhookDescription`.
+
+### Creating an Admission Webhook
+
+When developing an [admission webhook](/docs/reference/admission-webhooks) that will be managed by OLM you should consider the following constraints.
+
+#### Certificate Authority Constraints
+
+OLM is configured to provide each deployment with a single Certificate Authority (CA). The logic that generates and mounts the CA into the deployment was originally used by the [API Service](https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server/) lifecycle logic. As a result:
+
+- The tls Cert file will be mounted to the deployment at `/apiserver.local.config/certificates/apiserver.crt`
+- The tls Key file will be mounted to the deployment at `/apiserver.local.config/certificates/apiserver.key`
+
+#### Admission Webhook Rules Constraints
+
+Additionally, in an attempt to prevent operator from configuring the cluster into an unrecoverable state, OLM will place the CSV in the failed phase if the Rules defined in an admission webhook:
+
+- Intercept requests that target all groups
+- Intercept requests that target the `operators.coreos.com` group
+- Intercept requests that target the `ValidatingWebhookConfigurations` or `MutatingWebhookConfigurations` resources