Validating webhookedit

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.


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.

  1. A ValidatingWebhookConfiguration object that defines the validating webhook, targeting the right webhook path and resource. It must be created before starting the operator. The caBundle field can be automatically managed as part of the automatic certificate management (see below).
  2. A Kubernetes Service is used to expose the validating server, named elastic-webhook-server. It is in the same Namespace as the webhook server.
  3. 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 Configuring ECK for more information about the operator-roles flag.
  4. 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 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 cert-manager. See an example of the latter below.

Managing the webhook certificate with cert-manageredit

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 cert-manager documentation.

The following example shows how to create all the resources that a webhook requires to function.

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
kind: Issuer
  name: selfsigned-issuer
  namespace: elastic-system
  selfSigned: {}
kind: Certificate
  name: elastic-webhook
  namespace: elastic-system
  commonName: elastic-webhook.elastic-system.svc
  - elastic-webhook.elastic-system.svc.cluster.local
  - elastic-webhook.elastic-system.svc
    kind: Issuer
    name: selfsigned-issuer
  secretName: elastic-webhook-server-cert
apiVersion: v1
kind: Service
  name: elastic-webhook-server
  namespace: elastic-system
  - port: 443
    protocol: TCP
    targetPort: 9443
    control-plane: elastic-operator
  sessionAffinity: None
  type: ClusterIP
kind: ValidatingWebhookConfiguration
  annotations: elastic-system/elastic-webhook
- clientConfig:
    caBundle: Cg==
      name: elastic-webhook
      namespace: elastic-system
      # this is the path controller-runtime automatically generates
      path: /validate-elasticsearch-k8s-elastic-co-v1-elasticsearch
  failurePolicy: Ignore
  sideEffects: None
  - apiGroups:
    - v1
    - CREATE
    - UPDATE
    - elasticsearches

This example assumes that you have installed the operator in the elastic-system namespace.


Webhooks require network connectivity between the Kubernetes API server and the operator. See Webhook troubleshooting for more information about some known problems with some Kubernetes providers.