From 82e790f716e8d02a6e2c3b40d0fb134c223fe6b0 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 22 Nov 2019 10:37:12 +0100 Subject: [PATCH 01/15] Add some documentation about the webhook --- docs/index.asciidoc | 1 + docs/troubleshooting.asciidoc | 1 + docs/uninstalling-eck.asciidoc | 2 +- docs/webhook.asciidoc | 199 +++++++++++++++++++++++++++++++++ 4 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 docs/webhook.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 1a0ad7ed40..1ce0311145 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -23,6 +23,7 @@ include::apm-server.asciidoc[] include::custom-images.asciidoc[] include::operator-config.asciidoc[] include::licensing.asciidoc[] +include::webhook.asciidoc[] include::troubleshooting.asciidoc[] include::upgrading-eck.asciidoc[] include::uninstalling-eck.asciidoc[] diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc index ce7e8e6576..0cab228828 100644 --- a/docs/troubleshooting.asciidoc +++ b/docs/troubleshooting.asciidoc @@ -258,6 +258,7 @@ This can also be done for Kibana and APM Server. On startup, the operator deploys an https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/[admission webhook] that points to the operator's service. If this is inaccessible, you may see errors in your Kubernetes API server logs indicating that it cannot reach the service. A common cause may be that the operator pods are failing to start for some reason, or that the control plane is isolated from the operator pod by some mechanism (for instance via network policies or running the control plane externally as in https://github.com/elastic/cloud-on-k8s/issues/896#issuecomment-507224945[issue #869] and https://github.com/elastic/cloud-on-k8s/issues/1369[issue #1369]). +If you think that the validation is not done correctly you can also change the `failurePolicy` of the webhook configuration to `Fail`, which will cause creations to error out if there is an error contacting the webhook. [float] [id="{p}-ask-for-help"] === Ask for help diff --git a/docs/uninstalling-eck.asciidoc b/docs/uninstalling-eck.asciidoc index cb486cb7d3..6ff1147b98 100644 --- a/docs/uninstalling-eck.asciidoc +++ b/docs/uninstalling-eck.asciidoc @@ -27,5 +27,5 @@ And remove the webhook configuration: [source,shell] ---- -kubectl delete validatingwebhookconfigurations validating-webhook-configuration +kubectl delete validatingwebhookconfigurations elastic-es-validation.k8s.elastic.co ---- diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc new file mode 100644 index 0000000000..e456320744 --- /dev/null +++ b/docs/webhook.asciidoc @@ -0,0 +1,199 @@ +[id="{p}-webhook"] +== Validating webhook + +A validating webhook provides additional validation of Elasticsearch resources beyond what can be specified in OpenAPI specs. +This allows advanced validation to help prevent Elasticsearch resources that are invalid and will not function correctly +from being admitted by the Kubernetes API server, which can aid troubleshooting. + +[float] +=== Architecture + +The webhook is composed of 4 main components, here is a brief description of each of them to understand how they interact, +their naming and how they are managed. + +==== ValidatingWebhookConfiguration +It is the resource that defines the validating webhook. In ECK it is named `elastic-es-validation.k8s.elastic.co`. +It must be created before to start the operator, the `caBundle` field can be automatically managed as part of the +automatic certificate management _(see below)_. + +==== Webhook Service +A Kubernetes Service is used to expose the validating server, in ECK its name is fixed to `elastic-webhook-server`. +It lives in the same Namespace that the webhook server. + +=== Webhook Server +It is the component that actually validates the submitted resources. In ECK it is the operator itself when it +is configured to act the `webhook` role. See <<{p}-operator-config,Configuring ECK>> if want to learn more about the +`operator-roles` flag. + +=== The Certificates +A Secret contains the required certificates to secure the connection between the API server and the webhook. +Like the ValidatingWebhookConfiguration it must be created before to start the operator, even if it is empty. +If ECK has been installed with the provided manifest its name is `elastic-webhook-server-cert`. +The content of this Secret and the lifecycle of the certificates are automatically handled for you. You can disable +this feature if you want to manage the certificates by yourself or with the cert-manager, see an example below. + +[float] +=== Managing webhook certificate with cert-manager + +If the operator is currently running you first need to ensure that the automatic certificate management is disabled. +This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. + +Then if it is not already done you have to install cert-manager v0.11+ as described in their https://docs.cert-manager.io/en/latest/getting-started/install/[documentation]. + +Below is a complete example to create all of the resources necessary for the validating webhook to function. + +[source,yaml,subs="attributes,+macros"] +---- +cat $$<<$$EOF | kubectl apply -f - +--- +# this configures +# - a self signed cert-manager issuer +# - a service to point to the webhook +# - a self signed certificate for the webhook service +# - a validating webhook configuration +# - updates the ECK operator statefulset to enable the webhook +apiVersion: cert-manager.io/v1alpha2 +kind: Issuer +metadata: + name: selfsigned-issuer + namespace: elastic-system +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1alpha2 +kind: Certificate +metadata: + name: elastic-webhook + namespace: elastic-system +spec: + commonName: elastic-webhook.elastic-system.svc + dnsNames: + - elastic-webhook.elastic-system.svc.cluster.local + - elastic-webhook.elastic-system.svc + issuerRef: + kind: Issuer + name: selfsigned-issuer + secretName: elastic-webhook-server-cert +--- +apiVersion: v1 +kind: Service +metadata: + name: elastic-webhook-server + namespace: elastic-system +spec: + ports: + - port: 443 + protocol: TCP + targetPort: 9443 + selector: + control-plane: elastic-operator + sessionAffinity: None + type: ClusterIP +--- +apiVersion: admissionregistration.k8s.io/v1beta1 +kind: ValidatingWebhookConfiguration +metadata: + name: elastic-es-validation.k8s.elastic.co + annotations: + cert-manager.io/inject-ca-from: elastic-system/elastic-webhook +webhooks: +- clientConfig: + caBundle: Cg== + service: + name: elastic-webhook + namespace: elastic-system + # this is the path controller-runtime automatically generates + path: /validate-elasticsearch-k8s-elastic-co-{eck_crd_version}-elasticsearch + failurePolicy: Ignore + name: elastic-es-validation.k8s.elastic.co + sideEffects: None + rules: + - apiGroups: + - elasticsearch.k8s.elastic.co + apiVersions: + - {eck_crd_version} + operations: + - CREATE + - UPDATE + resources: + - elasticsearches +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + labels: + control-plane: elastic-operator + name: elastic-operator + namespace: elastic-system +spec: + podManagementPolicy: OrderedReady + replicas: 1 + revisionHistoryLimit: 10 + selector: + matchLabels: + control-plane: elastic-operator + serviceName: elastic-operator + template: + labels: + control-plane: elastic-operator + spec: + containers: + - args: + - manager + - --operator-roles + - all + - --enable-debug-logs=false + env: + - name: WEBHOOK_SECRET + value: elastic-webhook-server-cert + - name: OPERATOR_NAMESPACE + valueFrom: + fieldRef: + apiVersion: v1 + fieldPath: metadata.namespace + - name: OPERATOR_IMAGE + value: docker.elastic.co/eck/eck-operator:{eck_version} + image: docker.elastic.co/eck/eck-operator:{eck_version} + imagePullPolicy: Always + name: manager + ports: + - containerPort: 9443 + name: webhook-server + protocol: TCP + volumeMounts: + # this is the path controller-runtime looks for certs and should not be changed + - mountPath: /tmp/k8s-webhook-server/serving-certs + name: cert + readOnly: true + resources: + limits: + cpu: "1" + memory: 150Mi + requests: + cpu: 100m + memory: 50Mi + volumes: + - name: cert + secret: + defaultMode: 420 + secretName: elastic-webhook-server-cert + dnsPolicy: ClusterFirst + restartPolicy: Always + schedulerName: default-scheduler + securityContext: {} + serviceAccount: elastic-operator + serviceAccountName: elastic-operator + terminationGracePeriodSeconds: 10 + updateStrategy: + rollingUpdate: + partition: 0 + type: RollingUpdate +EOF +---- + +NOTE: This example assumes that you have installed the operator in the `elastic-system` namespace. + +=== Troubleshooting + +Webhooks rely on a good connectivity between the Kubernetes API server and the operator. +See <<{p}-troubleshooting,Webhook troubleshooting>> for more information about some known problems with some Kubernetes providers. From 123be806eb63e5af6ccbf3c0a15a2eb504512be4 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 22 Nov 2019 10:59:21 +0100 Subject: [PATCH 02/15] try fo fix doc compilation --- docs/webhook.asciidoc | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index e456320744..f674904584 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -5,28 +5,18 @@ A validating webhook provides additional validation of Elasticsearch resources b This allows advanced validation to help prevent Elasticsearch resources that are invalid and will not function correctly from being admitted by the Kubernetes API server, which can aid troubleshooting. -[float] === Architecture - The webhook is composed of 4 main components, here is a brief description of each of them to understand how they interact, their naming and how they are managed. -==== ValidatingWebhookConfiguration -It is the resource that defines the validating webhook. In ECK it is named `elastic-es-validation.k8s.elastic.co`. -It must be created before to start the operator, the `caBundle` field can be automatically managed as part of the +. A `ValidatingWebhookConfiguration` object that defines the validating webhook. In ECK it is named `elastic-es-validation.k8s.elastic.co`. It must be created before to start the operator, the `caBundle` field can be automatically managed as part of the automatic certificate management _(see below)_. - -==== Webhook Service -A Kubernetes Service is used to expose the validating server, in ECK its name is fixed to `elastic-webhook-server`. +. A Kubernetes Service is used to expose the validating server, in ECK its name is fixed to `elastic-webhook-server`. It lives in the same Namespace that the webhook server. - -=== Webhook Server -It is the component that actually validates the submitted resources. In ECK it is the operator itself when it +. A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it is configured to act the `webhook` role. See <<{p}-operator-config,Configuring ECK>> if want to learn more about the `operator-roles` flag. - -=== The Certificates -A Secret contains the required certificates to secure the connection between the API server and the webhook. +. A Secret which contains the required certificates to secure the connection between the API server and the webhook. Like the ValidatingWebhookConfiguration it must be created before to start the operator, even if it is empty. If ECK has been installed with the provided manifest its name is `elastic-webhook-server-cert`. The content of this Secret and the lifecycle of the certificates are automatically handled for you. You can disable From 89531ec6192d8da6b0eeeee2925e6cea04e3dbc3 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 22 Nov 2019 11:06:17 +0100 Subject: [PATCH 03/15] reintroduce floating title --- docs/webhook.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index f674904584..18c17855ab 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -5,6 +5,7 @@ A validating webhook provides additional validation of Elasticsearch resources b This allows advanced validation to help prevent Elasticsearch resources that are invalid and will not function correctly from being admitted by the Kubernetes API server, which can aid troubleshooting. +[float] === Architecture The webhook is composed of 4 main components, here is a brief description of each of them to understand how they interact, their naming and how they are managed. From ce2c84440d2553bbf452f433ee03ad499d9a5553 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 22 Nov 2019 14:10:15 +0100 Subject: [PATCH 04/15] add floating the troubleshooting title --- docs/webhook.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 18c17855ab..b0287d9696 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -184,6 +184,7 @@ EOF NOTE: This example assumes that you have installed the operator in the `elastic-system` namespace. +[float] === Troubleshooting Webhooks rely on a good connectivity between the Kubernetes API server and the operator. From 5aec2810959f0c7c1e9b10c0425c496190b29424 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 22 Nov 2019 15:05:27 +0100 Subject: [PATCH 05/15] No need to delete validatingwebhookconfigurations anymore --- docs/uninstalling-eck.asciidoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/uninstalling-eck.asciidoc b/docs/uninstalling-eck.asciidoc index 6ff1147b98..74ff118d49 100644 --- a/docs/uninstalling-eck.asciidoc +++ b/docs/uninstalling-eck.asciidoc @@ -22,10 +22,3 @@ Then, you can uninstall the operator: ---- kubectl delete -f https://download.elastic.co/downloads/eck/{eck_version}/all-in-one.yaml ---- - -And remove the webhook configuration: - -[source,shell] ----- -kubectl delete validatingwebhookconfigurations elastic-es-validation.k8s.elastic.co ----- From a413c0696021c61850b573d836695faabc8029ec Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Tue, 10 Dec 2019 13:13:58 +0100 Subject: [PATCH 06/15] changes from review --- docs/index.asciidoc | 1 - docs/operator-config.asciidoc | 2 ++ docs/webhook.asciidoc | 18 ++++++++---------- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 1ce0311145..1a0ad7ed40 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -23,7 +23,6 @@ include::apm-server.asciidoc[] include::custom-images.asciidoc[] include::operator-config.asciidoc[] include::licensing.asciidoc[] -include::webhook.asciidoc[] include::troubleshooting.asciidoc[] include::upgrading-eck.asciidoc[] include::uninstalling-eck.asciidoc[] diff --git a/docs/operator-config.asciidoc b/docs/operator-config.asciidoc index 564e68259d..badfa200f0 100644 --- a/docs/operator-config.asciidoc +++ b/docs/operator-config.asciidoc @@ -71,3 +71,5 @@ to: The `operator-roles` and `namespaces` flags have some intricacies that are worth discussing. A fully functioning operator will *require* both `global` and `namespace` roles running in the cluster (though potentially in different operator deployments). That is to say, with `--operator-roles=global,namespace` (or `--operator-roles=all`). If you want to limit the operator to a specific set of namespaces, you must set the `namespaces` flag as well. For example `--operator-roles=global,namespace --namespaces=my-namespace1,mynamespace2`. To have it manage all namespaces, you can simply omit the `namespaces` flag. The global role acts across namespaces and is not related to a specific deployment of the Elastic stack. The global operator deployed cluster-wide is responsible for high-level cross-cluster features. + +include::webhook.asciidoc[] \ No newline at end of file diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index b0287d9696..c8b4ca708c 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -1,9 +1,7 @@ [id="{p}-webhook"] == Validating webhook -A validating webhook provides additional validation of Elasticsearch resources beyond what can be specified in OpenAPI specs. -This allows advanced validation to help prevent Elasticsearch resources that are invalid and will not function correctly -from being admitted by the Kubernetes API server, which can aid troubleshooting. +A validating webhook provides additional validation of Elasticsearch resources, it gives you an immediate feedback on the Elasticsearch manifests you submit and allow you to catch errors right away before ECK even tries to fulfill your request. [float] === Architecture @@ -13,15 +11,15 @@ their naming and how they are managed. . A `ValidatingWebhookConfiguration` object that defines the validating webhook. In ECK it is named `elastic-es-validation.k8s.elastic.co`. It must be created before to start the operator, the `caBundle` field can be automatically managed as part of the automatic certificate management _(see below)_. . A Kubernetes Service is used to expose the validating server, in ECK its name is fixed to `elastic-webhook-server`. -It lives in the same Namespace that the webhook server. +It lives in the same Namespace as the webhook server. . A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it -is configured to act the `webhook` role. See <<{p}-operator-config,Configuring ECK>> if want to learn more about the +is configured to have the `webhook` role. See <<{p}-operator-config,Configuring ECK>> if you want to learn more about the `operator-roles` flag. . A Secret which contains the required certificates to secure the connection between the API server and the webhook. -Like the ValidatingWebhookConfiguration it must be created before to start the operator, even if it is empty. +Like the ValidatingWebhookConfiguration it must be created before starting the operator, even if it is empty. If ECK has been installed with the provided manifest its name is `elastic-webhook-server-cert`. -The content of this Secret and the lifecycle of the certificates are automatically handled for you. You can disable -this feature if you want to manage the certificates by yourself or with the cert-manager, see an example below. +The content of this Secret and the lifecycle of the certificates are automatically managed for you. You can disable +this feature if you want to setup the certificates by yourself or with the cert-manager, see an example for the latter below. [float] === Managing webhook certificate with cert-manager @@ -29,7 +27,7 @@ this feature if you want to manage the certificates by yourself or with the cert If the operator is currently running you first need to ensure that the automatic certificate management is disabled. This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. -Then if it is not already done you have to install cert-manager v0.11+ as described in their https://docs.cert-manager.io/en/latest/getting-started/install/[documentation]. +Then, if it is not already done you have to install cert-manager v0.11+ as described in the https://docs.cert-manager.io/en/latest/getting-started/install/[cert-manager documentation]. Below is a complete example to create all of the resources necessary for the validating webhook to function. @@ -187,5 +185,5 @@ NOTE: This example assumes that you have installed the operator in the `elastic- [float] === Troubleshooting -Webhooks rely on a good connectivity between the Kubernetes API server and the operator. +Webhooks require network connectivity between the Kubernetes API server and the operator. See <<{p}-troubleshooting,Webhook troubleshooting>> for more information about some known problems with some Kubernetes providers. From e74c19567b5c7249043f9dc02757fd614a85aeb7 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Tue, 10 Dec 2019 13:40:11 +0100 Subject: [PATCH 07/15] Try to fix section --- docs/troubleshooting.asciidoc | 1 + docs/webhook.asciidoc | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc index 0cab228828..67d7f2fa70 100644 --- a/docs/troubleshooting.asciidoc +++ b/docs/troubleshooting.asciidoc @@ -17,6 +17,7 @@ When things don't work as expected, you can investigate by taking the following - <<{p}-pause-controllers,Pause ECK controllers>> - <<{p}-get-k8s-events,Get Kubernetes events>> - <<{p}-exec-into-containers,Exec into containers>> +- <<{p}-webhook-troubleshooting,Webhook troubleshooting>> - <<{p}-ask-for-help,Ask for help>> [float] diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index c8b4ca708c..57d146e73c 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -1,5 +1,5 @@ [id="{p}-webhook"] -== Validating webhook +=== Validating webhook A validating webhook provides additional validation of Elasticsearch resources, it gives you an immediate feedback on the Elasticsearch manifests you submit and allow you to catch errors right away before ECK even tries to fulfill your request. From 00b5225d42b2d49ad40cde3924b3a80bd9c18694 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Tue, 10 Dec 2019 13:52:55 +0100 Subject: [PATCH 08/15] Fix troubleshooting link --- docs/webhook.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 57d146e73c..7e10025bdb 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -186,4 +186,4 @@ NOTE: This example assumes that you have installed the operator in the `elastic- === Troubleshooting Webhooks require network connectivity between the Kubernetes API server and the operator. -See <<{p}-troubleshooting,Webhook troubleshooting>> for more information about some known problems with some Kubernetes providers. +See <<{p}-webhook-troubleshooting,Webhook troubleshooting>> for more information about some known problems with some Kubernetes providers. From 9bc83c886d402e0487ec7a57a99c5080283a6f37 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Tue, 10 Dec 2019 14:27:16 +0100 Subject: [PATCH 09/15] Fix webhook validation name --- docs/webhook.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 7e10025bdb..3bf2f4f00f 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -82,7 +82,7 @@ spec: apiVersion: admissionregistration.k8s.io/v1beta1 kind: ValidatingWebhookConfiguration metadata: - name: elastic-es-validation.k8s.elastic.co + name: elastic-webhook.k8s.elastic.co annotations: cert-manager.io/inject-ca-from: elastic-system/elastic-webhook webhooks: From 7d9359d3521b2f70b18a1f258431af31d7a0560a Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Wed, 11 Dec 2019 17:05:20 +0100 Subject: [PATCH 10/15] Apply suggestions from code review Co-Authored-By: Anya Sabo <1638148+anyasabo@users.noreply.github.com> --- docs/troubleshooting.asciidoc | 2 +- docs/webhook.asciidoc | 25 +++++++++++-------------- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc index 67d7f2fa70..bc0f9ceb89 100644 --- a/docs/troubleshooting.asciidoc +++ b/docs/troubleshooting.asciidoc @@ -259,7 +259,7 @@ This can also be done for Kibana and APM Server. On startup, the operator deploys an https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/[admission webhook] that points to the operator's service. If this is inaccessible, you may see errors in your Kubernetes API server logs indicating that it cannot reach the service. A common cause may be that the operator pods are failing to start for some reason, or that the control plane is isolated from the operator pod by some mechanism (for instance via network policies or running the control plane externally as in https://github.com/elastic/cloud-on-k8s/issues/896#issuecomment-507224945[issue #869] and https://github.com/elastic/cloud-on-k8s/issues/1369[issue #1369]). -If you think that the validation is not done correctly you can also change the `failurePolicy` of the webhook configuration to `Fail`, which will cause creations to error out if there is an error contacting the webhook. +You can also change the https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#failure-policy[`failurePolicy`] of the webhook configuration to `Fail`, which will cause creations and updates to error out if there is an error contacting the webhook. [float] [id="{p}-ask-for-help"] === Ask for help diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 7e10025bdb..c40772b3a5 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -1,33 +1,30 @@ [id="{p}-webhook"] === Validating webhook -A validating webhook provides additional validation of Elasticsearch resources, it gives you an immediate feedback on the Elasticsearch manifests you submit and allow you to catch errors right away before ECK even tries to fulfill your request. +A validating webhook provides additional validation of Elasticsearch resources: it provides immediate feedback on the Elasticsearch manifests you submit, allowing you to catch errors right away before ECK even tries to fulfill your request. [float] === Architecture -The webhook is composed of 4 main components, here is a brief description of each of them to understand how they interact, -their naming and how they are managed. +The webhook is composed of 4 main components. Here is a brief description of each of them to understand how they interact, their naming, and how they are managed. -. A `ValidatingWebhookConfiguration` object that defines the validating webhook. In ECK it is named `elastic-es-validation.k8s.elastic.co`. It must be created before to start the operator, the `caBundle` field can be automatically managed as part of the -automatic certificate management _(see below)_. -. A Kubernetes Service is used to expose the validating server, in ECK its name is fixed to `elastic-webhook-server`. -It lives in the same Namespace as the webhook server. +. A `ValidatingWebhookConfiguration` object that defines the validating webhook, named `elastic-es-validation.k8s.elastic.co`. It must be created before starting the operator. The `caBundle` field can be automatically managed as part of the automatic certificate management _(see below)_. +. A Kubernetes Service is used to expose the validating server, named `elastic-webhook-server`. It is in the same Namespace as the webhook server. . A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it -is configured to have the `webhook` role. See <<{p}-operator-config,Configuring ECK>> if you want to learn more about the +is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the `operator-roles` flag. -. A Secret which contains the required certificates to secure the connection between the API server and the webhook. -Like the ValidatingWebhookConfiguration it must be created before starting the operator, even if it is empty. +. A Secret containing the required certificates to secure the connection between the API server and the webhook server. +Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. If ECK has been installed with the provided manifest its name is `elastic-webhook-server-cert`. The content of this Secret and the lifecycle of the certificates are automatically managed for you. You can disable -this feature if you want to setup the certificates by yourself or with the cert-manager, see an example for the latter below. +this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. [float] -=== Managing webhook certificate with cert-manager +=== Managing the webhook certificate with cert-manager -If the operator is currently running you first need to ensure that the automatic certificate management is disabled. +If ECK is currently running you first need to ensure that the automatic certificate management feature is disabled. This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. -Then, if it is not already done you have to install cert-manager v0.11+ as described in the https://docs.cert-manager.io/en/latest/getting-started/install/[cert-manager documentation]. +Then, cert-manager v0.11+ must be installed as described in the https://docs.cert-manager.io/en/latest/getting-started/install/[cert-manager documentation]. Below is a complete example to create all of the resources necessary for the validating webhook to function. From bc90579fb92f3e18f9db81550b987e3dad0df73b Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Wed, 11 Dec 2019 17:37:38 +0100 Subject: [PATCH 11/15] update from review --- docs/operator-config.asciidoc | 2 +- docs/webhook.asciidoc | 15 +++++---------- 2 files changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/operator-config.asciidoc b/docs/operator-config.asciidoc index badfa200f0..56dc662017 100644 --- a/docs/operator-config.asciidoc +++ b/docs/operator-config.asciidoc @@ -68,7 +68,7 @@ to: [id="{p}-ns-config"] === Namespace and role configuration -The `operator-roles` and `namespaces` flags have some intricacies that are worth discussing. A fully functioning operator will *require* both `global` and `namespace` roles running in the cluster (though potentially in different operator deployments). That is to say, with `--operator-roles=global,namespace` (or `--operator-roles=all`). If you want to limit the operator to a specific set of namespaces, you must set the `namespaces` flag as well. For example `--operator-roles=global,namespace --namespaces=my-namespace1,mynamespace2`. To have it manage all namespaces, you can simply omit the `namespaces` flag. +The `operator-roles` and `namespaces` flags have some intricacies that are worth discussing. A fully functioning operator will *require* both `global` and `namespace` roles running in the cluster (though potentially in different operator deployments). That is to say, with `--operator-roles=global,namespace` (or `--operator-roles=all`). To limit the operator to a specific set of namespaces, set the `namespaces` flag as well. For example `--operator-roles=global,namespace --namespaces=my-namespace1,mynamespace2`. To make the operator manage all namespaces, omit the `namespaces` flag. The global role acts across namespaces and is not related to a specific deployment of the Elastic stack. The global operator deployed cluster-wide is responsible for high-level cross-cluster features. diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 229ae68548..bd0c887990 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -9,24 +9,19 @@ The webhook is composed of 4 main components. Here is a brief description of eac . A `ValidatingWebhookConfiguration` object that defines the validating webhook, named `elastic-es-validation.k8s.elastic.co`. It must be created before starting the operator. The `caBundle` field can be automatically managed as part of the automatic certificate management _(see below)_. . A Kubernetes Service is used to expose the validating server, named `elastic-webhook-server`. It is in the same Namespace as the webhook server. -. A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it -is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the -`operator-roles` flag. +. A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the `operator-roles` flag. . A Secret containing the required certificates to secure the connection between the API server and the webhook server. -Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. -If ECK has been installed with the provided manifest its name is `elastic-webhook-server-cert`. -The content of this Secret and the lifecycle of the certificates are automatically managed for you. You can disable -this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. +Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. By default its name is `elastic-webhook-server-cert`. +The content of this Secret and the lifecycle of the certificates are automatically managed for you. You can disable this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. [float] === Managing the webhook certificate with cert-manager -If ECK is currently running you first need to ensure that the automatic certificate management feature is disabled. -This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. +If ECK is currently running you first need to ensure that the automatic certificate management feature is disabled. This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. Then, cert-manager v0.11+ must be installed as described in the https://docs.cert-manager.io/en/latest/getting-started/install/[cert-manager documentation]. -Below is a complete example to create all of the resources necessary for the validating webhook to function. +The following example shows how to create all the resources that a webhook requires to function. [source,yaml,subs="attributes,+macros"] ---- From 43ff98ad634950e2a0583dd167eb4954582d9e79 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Thu, 12 Dec 2019 10:06:09 +0100 Subject: [PATCH 12/15] Give more insight about the lifecycle of the certificate --- docs/webhook.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index bd0c887990..5ef87ab70a 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -12,7 +12,7 @@ The webhook is composed of 4 main components. Here is a brief description of eac . A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the `operator-roles` flag. . A Secret containing the required certificates to secure the connection between the API server and the webhook server. Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. By default its name is `elastic-webhook-server-cert`. -The content of this Secret and the lifecycle of the certificates are automatically managed for you. You can disable this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. +The content of this Secret and the lifecycle of the certificates are automatically managed for you. ECK generates a dedicated and separate certificate authority and ensures that every components are rotated before the expiration date. The certificate authority is also used to configure the `caBundle` field of the `ValidatingWebhookConfiguration`. You can disable this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. [float] === Managing the webhook certificate with cert-manager From 63dac93d44a4336d4d7cd06e73add021558bf145 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Thu, 12 Dec 2019 10:11:24 +0100 Subject: [PATCH 13/15] update from review --- docs/webhook.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 5ef87ab70a..c2e62076bb 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -12,12 +12,12 @@ The webhook is composed of 4 main components. Here is a brief description of eac . A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the `operator-roles` flag. . A Secret containing the required certificates to secure the connection between the API server and the webhook server. Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. By default its name is `elastic-webhook-server-cert`. -The content of this Secret and the lifecycle of the certificates are automatically managed for you. ECK generates a dedicated and separate certificate authority and ensures that every components are rotated before the expiration date. The certificate authority is also used to configure the `caBundle` field of the `ValidatingWebhookConfiguration`. You can disable this feature if you want to setup the certificates by yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. +The content of this Secret and the lifecycle of the certificates are automatically managed for you. ECK generates a dedicated and separate certificate authority and ensures that every components are rotated before the expiration date. The certificate authority is also used to configure the `caBundle` field of the `ValidatingWebhookConfiguration`. You can disable this feature if you want to manage the certificates yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. [float] === Managing the webhook certificate with cert-manager -If ECK is currently running you first need to ensure that the automatic certificate management feature is disabled. This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. +If ECK is currently running you first must ensure that the automatic certificate management feature is disabled. This can be done by updating the operator deployment manifest and adding the `--manage-webhook-certs=false` flag. Then, cert-manager v0.11+ must be installed as described in the https://docs.cert-manager.io/en/latest/getting-started/install/[cert-manager documentation]. From 6b7253ac75709de6a811576d522394352da0f871 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Thu, 12 Dec 2019 21:10:47 +0100 Subject: [PATCH 14/15] Update docs/webhook.asciidoc Co-Authored-By: Anya Sabo <1638148+anyasabo@users.noreply.github.com> --- docs/webhook.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index c2e62076bb..87f4175e4a 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -12,7 +12,7 @@ The webhook is composed of 4 main components. Here is a brief description of eac . A webhook server that actually validates the submitted resources. In ECK it is the operator itself when it is configured with the `webhook` role. See <<{p}-operator-config,Configuring ECK>> for more information about the `operator-roles` flag. . A Secret containing the required certificates to secure the connection between the API server and the webhook server. Like the ValidatingWebhookConfiguration, it must be created before starting the operator, even if it is empty. By default its name is `elastic-webhook-server-cert`. -The content of this Secret and the lifecycle of the certificates are automatically managed for you. ECK generates a dedicated and separate certificate authority and ensures that every components are rotated before the expiration date. The certificate authority is also used to configure the `caBundle` field of the `ValidatingWebhookConfiguration`. You can disable this feature if you want to manage the certificates yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. +The content of this Secret and the lifecycle of the certificates are automatically managed for you. ECK generates a dedicated and separate certificate authority and ensures that all components are rotated before the expiration date. The certificate authority is also used to configure the `caBundle` field of the `ValidatingWebhookConfiguration`. You can disable this feature if you want to manage the certificates yourself or with https://github.com/jetstack/cert-manager[cert-manager]. See an example of the latter below. [float] === Managing the webhook certificate with cert-manager From caae516544cd3991216ea83b6e17784726a37e47 Mon Sep 17 00:00:00 2001 From: Michael Morello Date: Fri, 13 Dec 2019 09:36:24 +0100 Subject: [PATCH 15/15] Remove sset --- docs/webhook.asciidoc | 72 ------------------------------------------- 1 file changed, 72 deletions(-) diff --git a/docs/webhook.asciidoc b/docs/webhook.asciidoc index 87f4175e4a..c33a9dda97 100644 --- a/docs/webhook.asciidoc +++ b/docs/webhook.asciidoc @@ -32,7 +32,6 @@ cat $$<<$$EOF | kubectl apply -f - # - a service to point to the webhook # - a self signed certificate for the webhook service # - a validating webhook configuration -# - updates the ECK operator statefulset to enable the webhook apiVersion: cert-manager.io/v1alpha2 kind: Issuer metadata: @@ -98,77 +97,6 @@ webhooks: - UPDATE resources: - elasticsearches ---- -apiVersion: apps/v1 -kind: StatefulSet -metadata: - labels: - control-plane: elastic-operator - name: elastic-operator - namespace: elastic-system -spec: - podManagementPolicy: OrderedReady - replicas: 1 - revisionHistoryLimit: 10 - selector: - matchLabels: - control-plane: elastic-operator - serviceName: elastic-operator - template: - labels: - control-plane: elastic-operator - spec: - containers: - - args: - - manager - - --operator-roles - - all - - --enable-debug-logs=false - env: - - name: WEBHOOK_SECRET - value: elastic-webhook-server-cert - - name: OPERATOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace - - name: OPERATOR_IMAGE - value: docker.elastic.co/eck/eck-operator:{eck_version} - image: docker.elastic.co/eck/eck-operator:{eck_version} - imagePullPolicy: Always - name: manager - ports: - - containerPort: 9443 - name: webhook-server - protocol: TCP - volumeMounts: - # this is the path controller-runtime looks for certs and should not be changed - - mountPath: /tmp/k8s-webhook-server/serving-certs - name: cert - readOnly: true - resources: - limits: - cpu: "1" - memory: 150Mi - requests: - cpu: 100m - memory: 50Mi - volumes: - - name: cert - secret: - defaultMode: 420 - secretName: elastic-webhook-server-cert - dnsPolicy: ClusterFirst - restartPolicy: Always - schedulerName: default-scheduler - securityContext: {} - serviceAccount: elastic-operator - serviceAccountName: elastic-operator - terminationGracePeriodSeconds: 10 - updateStrategy: - rollingUpdate: - partition: 0 - type: RollingUpdate EOF ----