Add docs

Signed-off-by: Per Goncalves da Silva <[email protected]>

Author: Per Goncalves da Silva

docs/draft/howto/enable-webhook-support.md

@@ -0,0 +1,62 @@
+## Installation of Bundles containing Webhooks
+
+!!! note
+This feature is still in *alpha*. Either the `WebhookProviderCertManager`, or the `WebhookProviderOpenshiftServiceCA`, feature-gate 
+must be enabled to make use of it. See the instructions below on how to enable the feature-gate.
+
+OLMv1 currently does not support the installation of bundles containing webhooks. The webhook support feature enables this capability.
+Webhooks, or more concretely Admission Webhooks, are part of Kuberntes' [Dynamic Admission Control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
+feature. Webhooks run as services called by the kube-apiservice in due course of processing a resource related request. They can be used to validate resources, ensure reasonable default values,
+are set, or aid in the migration to new CustomResourceDefinition schema. The communication with the webhook service is secured by TLS. In OLMv1, the TLS certificate is managed by a 
+certificate provider. Currently, two certificate providers are supported: CertManager and Openshift-ServiceCA. The certificate provider to use given by the feature-gate:
+
+- `WebhookProviderCertManager` for [CertManager](https://cert-manager.io/)
+- `WebhookProviderOpenshiftServiceCA` for [Openshift-ServiceCA](https://github.com/openshift/service-ca-operator)
+
+As CertManager is already installed with OLMv1, we suggest using `WebhookProviderCertManager`.
+
+### Update OLM to enable Feature
+
+```terminal title=Enable WebhookProviderCertManager feature
+kubectl kustomize config/overlays/featuregate/webhook-provider-certmanager | kubectl apply -f -
+```
+
+Or,
+
+```terminal title=Enable WebhookProviderOpenshiftServiceCA feature
+kubectl kustomize config/overlays/featuregate/webhook-provider-openshift-serviceca | kubectl apply -f -
+```
+
+Then,
+
+```terminal title=Wait for rollout to complete
+kubectl rollout status -n olmv1-system deployment/operator-controller-controller-manager 
+```
+
+### Notes on the generated certificate
+
+#### CertManager
+
+The generated certificate maintains a high-level of parity with the certificate generated by OLMv0:
+- Self-signed
+- Two validity period, rotating 24h before expiry
+- Valid for the webhook service's DNSNames:
+  - <service-name>.<namespace>
+  - <service-name>.<namespace>.svc
+  - <service-name>.<namespace>.svc.cluster.local
+
+#### Openshift-ServiceCA
+
+Generation and rotation are completely governed by [Openshift-ServiceCA](https://github.com/openshift/service-ca-operator)
+
+### How does it work?
+
+There's no change in the installation flow. Just install a bundle containing webhooks as you would any other.
+
+### Demo
+
+!!! note
+As there is no difference in usage or experience between the CertManager and Openshift-ServiceCA variants, only
+the cert-manager variant is demoed.
+
+[![asciicast](https://asciinema.org/a/GyjsB129GkUadeuxFhNuG4FcS.svg)](https://asciinema.org/a/GyjsB129GkUadeuxFhNuG4FcS)