Add OLM webhook support

Author: adellape

_topic_map.yml

@@ -708,6 +708,9 @@ Topics:
 - Name: Creating policy for Operator installations and upgrades
   File: olm-creating-policy
   Distros: openshift-origin,openshift-enterprise,openshift-webscale
+- Name: Managing admission webhooks in OLM
+  File: olm-webhooks
+  Distros: openshift-origin,openshift-enterprise,openshift-webscale
 - Name: Managing custom catalogs
   File: olm-managing-custom-catalogs
   Distros: openshift-origin,openshift-enterprise,openshift-webscale

modules/olm-defining-csv-webhooks.adoc

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * operators/olm-webhooks.adoc
+
+[id="olm-defining-csv-webhook_{context}"]
+= Defining webhooks in a CSV
+
+The ClusterServiceVersion (CSV) resource includes a `webhookdefinitions` section
+to define validating and mutating admission webhooks that ship with an Operator.
+For example:
+
+.CSV containing a validating admission webhook
+[source,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"
+...
+----
+
+OLM requires that you define the following:
+
+* The `type` field must be set to either `ValidatingAdmissionWebhook` or
+`MutatingAdmissionWebhook`, or the CSV will be placed in a failed phase. * The
+CSV must contain a Deployment whose name is equivalent to the value supplied in
+the `deploymentName` field of the `webhookdefinition`.
+
+When the webhook is created, OLM ensures that the webhook only acts upon
+namespaces that match the OperatorGroup that the Operator is deployed in.

modules/olm-webhook-considerations.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * operators/olm-webhooks.adoc
+
+[id="olm-webhook-considerations_{context}"]
+= Webhook considerations
+
+When developing an admission webhook to be managed by OLM, consider the
+following constraints:
+
+[discrete]
+[id="olm-webhook-ca_{context}"]
+=== 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 APIService lifecycle logic. As a result:
+
+* The TLS certificate file is mounted to the Deployment at
+`/apiserver.local.config/certificates/apiserver.crt`.
+* The TLS key file is mounted to the Deployment at
+`/apiserver.local.config/certificates/apiserver.key`.
+
+[discrete]
+[id="olm-webhook-rules_{context}"]
+=== Admission webhook rules constraints
+
+To prevent an Operator from configuring the cluster into an unrecoverable state,
+OLM places the CSV in the failed phase if the rules defined in an admission
+webhook intercept any of the following requests:
+
+* Requests that target all groups
+* Requests that target the `operators.coreos.com` group
+* Requests that target the `ValidatingWebhookConfigurations` or
+`MutatingWebhookConfigurations` resources

operators/olm-webhooks.adoc

@@ -0,0 +1,19 @@
+[id="olm-webhooks"]
+= Managing admission webhooks in Operator Lifecycle Manager
+include::modules/common-attributes.adoc[]
+:context: olm-webhooks
+
+toc::[]
+
+Validating and mutating admission webhooks allow Operator authors to intercept,
+modify, and accept or reject resources before they are handled by the Operator
+controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these
+webhooks when they are shipped alongside your Operator.
+
+include::modules/olm-defining-csv-webhooks.adoc[leveloffset=+1]
+include::modules/olm-webhook-considerations.adoc[leveloffset=+1]
+
+[id="olm-webhooks-additional-resources"]
+== Additional resources
+
+* xref:../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plug-ins]