From b09a8f46bf95243efeb408153145fe677ab5a63b Mon Sep 17 00:00:00 2001 From: Alex Dellapenta Date: Tue, 6 Oct 2020 16:16:48 -0600 Subject: [PATCH] Add conversion webhooks for OLM --- _topic_map.yml | 5 +- modules/olm-defining-csv-webhooks.adoc | 155 ++++++++++++------ modules/olm-webhook-considerations.adoc | 35 +++- .../operator_sdk/osdk-generating-csvs.adoc | 11 ++ operators/understanding/olm/olm-webhooks.adoc | 25 +++ operators/user/olm-webhooks.adoc | 20 --- 6 files changed, 175 insertions(+), 76 deletions(-) create mode 100644 operators/understanding/olm/olm-webhooks.adoc delete mode 100644 operators/user/olm-webhooks.adoc diff --git a/_topic_map.yml b/_topic_map.yml index ae6838a58a..cacb32fde6 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -825,6 +825,8 @@ Topics: File: olm-understanding-operatorgroups - Name: Metrics File: olm-understanding-metrics + - Name: Webhooks + File: olm-webhooks - Name: OperatorHub Distros: openshift-enterprise,openshift-webscale,openshift-origin File: olm-understanding-operatorhub @@ -846,9 +848,6 @@ Topics: - Name: Installing Operators in your namespace File: olm-installing-operators-in-namespace Distros: openshift-enterprise,openshift-webscale,openshift-origin - - Name: Managing admission webhooks in OLM - File: olm-webhooks - Distros: openshift-origin,openshift-enterprise,openshift-webscale - Name: Administrator tasks Dir: admin Topics: diff --git a/modules/olm-defining-csv-webhooks.adoc b/modules/olm-defining-csv-webhooks.adoc index 1835658d8e..b4c3c85fb0 100644 --- a/modules/olm-defining-csv-webhooks.adoc +++ b/modules/olm-defining-csv-webhooks.adoc @@ -1,57 +1,118 @@ // Module included in the following assemblies: // -// * operators/olm-webhooks.adoc +// * operators/operator_sdk/osdk-generating-csvs.adoc [id="olm-defining-csv-webhook_{context}"] -= Defining webhooks in a CSV += Defining webhooks -The ClusterServiceVersion (CSV) resource includes a `webhookdefinitions` section -to define validating and mutating admission webhooks that ship with an Operator. -For example: +Webhooks allow Operator authors to intercept, modify, and accept or reject +resources before they are saved to the object store and handled by the Operator +controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these +webhooks when they are shipped alongside your Operator. -.CSV containing a validating admission webhook +The ClusterServiceVersion (CSV) resource of an Operator can include a +`webhookdefinitions` section to define the following types of webhooks: + +* Admission webhooks (validating and mutating) +* Conversion webhooks + +.Procedure + +* Add a `webhookdefinitions` section to the `spec` section of the CSV of your +Operator and include any webhook definitions using a `type` of +`ValidatingAdmissionWebhook`, `MutatingAdmissionWebhook`, or +`ConversionWebhook`. The following example contains all three types of webhooks: ++ +.CSV containing webhooks [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" + apiVersion: operators.coreos.com/v1alpha1 + kind: ClusterServiceVersion + metadata: + name: webhook-operator.v0.0.1 + spec: + customresourcedefinitions: + owned: + - kind: WebhookTest + name: webhooktests.webhook.operators.coreos.io <1> + version: v1 + install: + spec: + deployments: + - name: webhook-operator-webhook + ... + ... + ... + strategy: deployment + installModes: + - supported: false + type: OwnNamespace + - supported: false + type: SingleNamespace + - supported: false + type: MultiNamespace + - supported: true + type: AllNamespaces + webhookdefinitions: + - type: ValidatingAdmissionWebhook <2> + admissionReviewVersions: + - v1beta1 + - v1 + containerPort: 443 + targetPort: 4343 + deploymentName: webhook-operator-webhook + failurePolicy: Fail + generateName: vwebhooktest.kb.io + rules: + - apiGroups: + - webhook.operators.coreos.io + apiVersions: + - v1 + operations: + - CREATE + - UPDATE + resources: + - webhooktests + sideEffects: None + webhookPath: /validate-webhook-operators-coreos-io-v1-webhooktest + - type: MutatingAdmissionWebhook <3> + admissionReviewVersions: + - v1beta1 + - v1 + containerPort: 443 + targetPort: 4343 + deploymentName: webhook-operator-webhook + failurePolicy: Fail + generateName: mwebhooktest.kb.io + rules: + - apiGroups: + - webhook.operators.coreos.io + apiVersions: + - v1 + operations: + - CREATE + - UPDATE + resources: + - webhooktests + sideEffects: None + webhookPath: /mutate-webhook-operators-coreos-io-v1-webhooktest + - type: ConversionWebhook <4> + admissionReviewVersions: + - v1beta1 + - v1 + containerPort: 443 + targetPort: 4343 + deploymentName: webhook-operator-webhook + generateName: cwebhooktest.kb.io + sideEffects: None + webhookPath: /convert + conversionCRDs: + - webhooktests.webhook.operators.coreos.io <5> ... ---- - -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. +<1> The CRDs targeted by the conversion webhook must exist here. +<2> A validating admission webhook. +<3> A mutating admission webhook. +<4> A conversion webhook. +<5> The `spec.PreserveUnknownFields` property of each CRD must be set to `false` or +`nil`. diff --git a/modules/olm-webhook-considerations.adoc b/modules/olm-webhook-considerations.adoc index be9e9fa50c..1b85e24124 100644 --- a/modules/olm-webhook-considerations.adoc +++ b/modules/olm-webhook-considerations.adoc @@ -1,12 +1,22 @@ // Module included in the following assemblies: // -// * operators/olm-webhooks.adoc +// * operators/operator_sdk/osdk-generating-csvs.adoc [id="olm-webhook-considerations_{context}"] -= Webhook considerations += Webhook considerations for OLM -When developing an admission webhook to be managed by OLM, consider the -following constraints: +When deploying an Operator with webhooks using Operator Lifecycle Manager (OLM), +you must define the following: + +* The `type` field must be set to either `ValidatingAdmissionWebhook`, +`MutatingAdmissionWebhook`, or `ConversionWebhook`, 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. [discrete] [id="olm-webhook-ca_{context}"] @@ -14,7 +24,7 @@ following 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: +originally used by the API Service lifecycle logic. As a result: * The TLS certificate file is mounted to the Deployment at `/apiserver.local.config/certificates/apiserver.crt`. @@ -22,7 +32,7 @@ originally used by the APIService lifecycle logic. As a result: `/apiserver.local.config/certificates/apiserver.key`. [discrete] -[id="olm-webhook-rules_{context}"] +[id="olm-admission-webhook-constraints_{context}"] === Admission webhook rules constraints To prevent an Operator from configuring the cluster into an unrecoverable state, @@ -33,3 +43,16 @@ webhook intercept any of the following requests: * Requests that target the `operators.coreos.com` group * Requests that target the `ValidatingWebhookConfigurations` or `MutatingWebhookConfigurations` resources + +[discrete] +[id="olm-conversion-webhook-constraints_{context}"] +=== Conversion webhook constraints + +OLM places the CSV in the failed phase if a conversion +webhook definition does not adhere to the following constraints: + +* CSVs featuring a conversion webhook can only support the `AllNamespaces` InstallMode. +* The CRD targeted by the conversion webhook must have its +`spec.preserveUnknownFields` field set to `false` or `nil`. +* The conversion webhook defined in the CSV must target an owned CRD. +* There can only be one conversion webhook on the entire cluster for a given CRD. diff --git a/operators/operator_sdk/osdk-generating-csvs.adoc b/operators/operator_sdk/osdk-generating-csvs.adoc index 8cc0e5db7c..4a3f209f49 100644 --- a/operators/operator_sdk/osdk-generating-csvs.adoc +++ b/operators/operator_sdk/osdk-generating-csvs.adoc @@ -58,6 +58,17 @@ specification for more information on manifest lists. include::modules/olm-arch-os-support.adoc[leveloffset=+2] include::modules/osdk-suggested-namespace.adoc[leveloffset=+1] +include::modules/olm-defining-csv-webhooks.adoc[leveloffset=+1] +.Additional resources + +* xref:../../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plug-ins] +* Kubernetes documentation: +** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook[Validating admission webhooks] +** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook[Mutating admission webhooks] +** link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion[Conversion webhooks] + +include::modules/olm-webhook-considerations.adoc[leveloffset=+2] + include::modules/osdk-crds.adoc[leveloffset=+1] include::modules/osdk-owned-crds.adoc[leveloffset=+2] include::modules/osdk-required-crds.adoc[leveloffset=+2] diff --git a/operators/understanding/olm/olm-webhooks.adoc b/operators/understanding/olm/olm-webhooks.adoc new file mode 100644 index 0000000000..583ee1a725 --- /dev/null +++ b/operators/understanding/olm/olm-webhooks.adoc @@ -0,0 +1,25 @@ +[id="olm-webhooks"] += Webhook management in Operator Lifecycle Manager +include::modules/common-attributes.adoc[] +:context: olm-webhooks + +toc::[] + +Webhooks allow Operator authors to intercept, modify, and accept or reject +resources before they are saved to the object store and handled by the Operator +controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these +webhooks when they are shipped alongside your Operator. + +See +xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-defining-csv-webhook_osdk-generating-csvs[Generating a ClusterServiceVersion (CSV)] +for details on how an Operator developer can define webhooks for their Operator, +as well as considerations when running on OLM. + +[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] +* Kubernetes documentation: +** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook[Validating admission webhooks] +** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook[Mutating admission webhooks] +** link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion[Conversion webhooks] diff --git a/operators/user/olm-webhooks.adoc b/operators/user/olm-webhooks.adoc deleted file mode 100644 index 0c7083afbe..0000000000 --- a/operators/user/olm-webhooks.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[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 saved to the object store -and 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]