Merge pull request #70 from awgreene/link-to-sdk-docs

Update OLM Webhook document

Author: anik120

content/en/docs/Concepts/crds/CatalogSource.md

@@ -5,7 +5,7 @@ weight: 3
 
 A CatalogSource represents a store of metadata that OLM can query to discover and install operators and their dependencies.
 
-The `.spec` of a CatalogSource indicates to how to construct a pod or how to talk to a service that serves the [operator-registry grpc api](/docs/concepts/olm-architecture/operator-registry/using-catalog-locally). 
+The `.spec` of a CatalogSource indicates to how to construct a pod or how to talk to a service that serves the [operator-registry grpc api](/docs/concepts/olm-architecture/operator-registry/using-a-catalog-locally). 
 
 There are three primary types:
 

content/en/docs/Concepts/olm-architecture/operator-registry/building-a-catalog.md

@@ -79,7 +79,7 @@ For more detail on using `opm` to generate index images, take a look at the [doc
 <pre></pre>
 ## Where should I go next?
 
-* [Use the catalog of operators locally](/docs/concepts/olm-architecture/operator-registry/using-catalog-locally/): Test your catalog locally 
-* [Using a Catalog with OLM](/docs/concepts/olm-architecture/operator-registry/using-catalog-with-olm/): Make your operator available for OLM in a cluster
+* [Use the catalog of operators locally](/docs/concepts/olm-architecture/operator-registry/using-a-catalog-locally): Test your catalog locally 
+* [Using a Catalog with OLM](/docs/concepts/olm-architecture/operator-registry/using-catalog-with-olm): Make your operator available for OLM in a cluster
 
 

content/en/docs/advanced-tasks/adding-admission-and-conversion-webhooks.md

@@ -15,30 +15,42 @@ In addition to these fields, OLM requires that you define:
 - The `Type` of the Webhook, which must be set to `ValidatingAdmissionWebhook`, `MutatingAdmissionWebhook`, or `ConversionWebhook`
 - The `DeploymentName` that OLM must mount the CA Cert information into, this should match the name of a deployment defined in the CSV
 
-## Deploying an operator with webhooks using OLM
+## Creating an Operator with a Webhook
+
+This document will not cover the steps required to create an operator that includes an admission or conversion webhook. If you are interested in creating such an operator, please refer to the following documentation provided by the Operator-SDK and Kubebuilder projects:
 
-### OLM Requirements for Operators with Webhooks
+- [Creating an Admission Webhook](https://sdk.operatorframework.io/docs/building-operators/golang/webhooks/)
+- [Creating a Conversion Webhook](https://book.kubebuilder.io/multiversion-tutorial/conversion.html)
+
+## Deploying an operator with webhooks using OLM
 
 OLM has a few constraints that must be considered when developing an operator featuring validating, mutating, or conversion webhooks.
 
-#### Certificate Authority Requirements
+### Certificate Authority Requirements
+
+OLM will create and mount a self-signed Certificate Authority (CA) to each deployment that contains a webhook as defined in the CSV. The certificates generated by OLM will expire after 2 years, at which point OLM will generate new certificates and redeploy the operator. The logic that generates and mounts the CA into the deployment was originally developed for the [API Service](https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server/) lifecycle logic and has been expanded for use with webhooks.
+
+OLM will mount the certificates at the default location that operators built with Kubebuilder and the Operator-SDK expect the certificates, specifically
+
+- The TLS Cert file will be mounted to the deployment at `/tmp/k8s-webhook-server/serving-certs/tls.cert`
+- The TLS Key file will be mounted to the deployment at `/tmp/k8s-webhook-server/serving-certs/tls.key`
 
-OLM is configured to create a single Certificate Authority (CA) for each webhook deployment. 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:
+> Note: When OLM was released, the CAs meant for Webhooks were mounted to the same location as defined by the existing API Service Lifecycle code. In an effort to remain backwards compatible, the certificates are also mounted to the following locations:
 
-- 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`
+- The TLS Cert file will also be mounted to the deployment at `/apiserver.local.config/certificates/apiserver.crt`
+- The TLS Key file will also be mounted to the deployment at `/apiserver.local.config/certificates/apiserver.key`
 
-If the operator was built with [Kubebuilder](https://book.kubebuilder.io/) or the [Operator-SDK](https://github.com/operator-framework/operator-sdk), [this commit](https://github.com/awgreene/webhook-operator/commit/3ef33a1b7090180bd873fb2ecbcddb9a92a79f0b) can be used as a reference to update where the operator's webhook expects the Certs mounted by OLM.
+OLM does not allow users to specify a mount location or name for the certificates. This issue should be addressed once OLM makes the decision to offload the management of CAs to projects such as [Cert-Manager](https://github.com/jetstack/cert-manager) and the [Service-CA Operator](https://github.com/openshift/service-ca-operator), this work can be tracked [here](https://github.com/operator-framework/operator-lifecycle-manager/issues/1805).
 
-#### Admission Webhook Rule Requirements
+### Admission Webhook Rule Requirements
 
 When developing an admission webhook please be aware that 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
 
-#### Conversion Webhook Rules Requirements
+### Conversion Webhook Rules Requirements
 
 - CSVs featuring a conversion webhook may only support the `AllNamespaces` installMode
 - The CRD targeted by the Conversion webhook must have its `spec.preserveUnknownFields` field set to `false` or `nil`