openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

Add conversion webhooks for OLM

Browse Source
This commit is contained in:
Alex Dellapenta
2020-10-06 16:16:48 -06:00
committed by openshift-cherrypick-robot
parent aef5f2f83b
commit b09a8f46bf
6 changed files with 175 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
_topic_map.yml
View File

@@ -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:

155
modules/olm-defining-csv-webhooks.adoc
View File

@@ -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`.

35
modules/olm-webhook-considerations.adoc
View File

@@ -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.

11
operators/operator_sdk/osdk-generating-csvs.adoc
View File

@@ -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]

25
operators/understanding/olm/olm-webhooks.adoc Normal file
View File

@@ -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]

20
operators/user/olm-webhooks.adoc
View File

@@ -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]