docs: validating webhook (kedacore#1027)

* docs: validating webhook Signed-off-by: Jorge Turrado <[email protected]> * update webhooks prom metrics Signed-off-by: Jorge Turrado <[email protected]> * add explanation about how to use user given certs Signed-off-by: Jorge Turrado <[email protected]> * update pictures Signed-off-by: Jorge Turrado <[email protected]> * apply feedback Signed-off-by: Jorge Turrado <[email protected]> * udpate Signed-off-by: Jorge Turrado <[email protected]> * move the section to concepts Signed-off-by: Jorge Turrado <[email protected]> * update picture (1) Signed-off-by: Jorge Turrado <[email protected]> * update old arch Signed-off-by: Jorge Turrado <[email protected]> * update installation section Signed-off-by: Jorge Turrado <[email protected]> * split admission webhooks content Signed-off-by: Jorge Turrado <[email protected]> * explain webhooks goal Signed-off-by: Jorge Turrado <[email protected]> * add new line Signed-off-by: Jorge Turrado <[email protected]> * update docs with the new process to disable cert generation Signed-off-by: Jorge Turrado <[email protected]> * update typo Signed-off-by: Jorge Turrado <[email protected]> * apply feedback Signed-off-by: Jorge Turrado <[email protected]> * update resources Signed-off-by: Jorge Turrado <[email protected]> * apply feedback Signed-off-by: Jorge Turrado <[email protected]> Signed-off-by: Jorge Turrado <[email protected]> Signed-off-by: Jorge Turrado <[email protected]>
DmitrySenin · Jan 9, 2023 · 8287884 · 8287884
1 parent 6b8f600
commit 8287884
Show file tree

Hide file tree

Showing 23 changed files with 92 additions and 23 deletions.
diff --git a/content/docs/1.4/concepts/_index.md b/content/docs/1.4/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/1.5/concepts/_index.md b/content/docs/1.5/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.0/concepts/_index.md b/content/docs/2.0/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.1/concepts/_index.md b/content/docs/2.1/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.10/concepts/_index.md b/content/docs/2.10/concepts/_index.md
@@ -12,10 +12,11 @@ weight = 1
 
 ## How KEDA works
 
-KEDA performs two key roles within Kubernetes:
+KEDA performs three key roles within Kubernetes:
 
 1. **Agent** — KEDA activates and deactivates Kubernetes [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment) to scale to and from zero on no events. This is one of the primary roles of the `keda-operator` container that runs when you install KEDA.
-1. **Metrics** — KEDA acts as a [Kubernetes metrics server](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-custom-metrics) that exposes rich event data like queue length or stream lag to the Horizontal Pod Autoscaler to drive scale out.  It is up to the Deployment to consume the events directly from the source.  This preserves rich event integration and enables gestures like completing or abandoning queue messages to work out of the box.  The metric serving is the primary role of the `keda-operator-metrics-apiserver` container that runs when you install KEDA.
+2. **Metrics** — KEDA acts as a [Kubernetes metrics server](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-custom-metrics) that exposes rich event data like queue length or stream lag to the Horizontal Pod Autoscaler to drive scale out.  It is up to the Deployment to consume the events directly from the source.  This preserves rich event integration and enables gestures like completing or abandoning queue messages to work out of the box.  The metric serving is the primary role of the `keda-operator-metrics-apiserver` container that runs when you install KEDA.
+3. **Admission Webhooks** - Automatically validate resource changes to prevent misconfiguration and enforce best practices by using an [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/). As an example, it will prevent multiple ScaledObjects to target the same scale target.
 
 ## Architecture
 

diff --git a/content/docs/2.10/concepts/admission-webhooks.md b/content/docs/2.10/concepts/admission-webhooks.md
@@ -0,0 +1,18 @@
++++
+title = "Admission Webhooks"
+description = "Automatically validate resource changes to prevent misconfiguration and enforce best practices"
+weight = 600
++++
+
+> 💡 The Admission Webhooks are an opt-in feature and will become an opt-out feature as of KEDA v2.12.
+
+There are some several misconfiguration scenarios that can produce scaling problems in productive workloads, for example: in Kubernetes a single workload should never be scaled by 2 or more HPA because that will produce conflicts and unintended behaviors.
+
+Some errors with data format can be detected during the model validation, but these misconfigurations can't be detected in that step because the model is correct indeed. For trying to avoid those misconfigurations at data plane detecting them early, admission webhooks validate all the incoming (KEDA) resources (new or updated) and reject any resource that doesn't match the rules below.
+
+### Prevention Rules
+
+KEDA will block all incoming changes to `ScaledObject` that don't match these rules:
+
+- The scaled workload (`scaledobject.spec.scaleTargetRef`) is already autoscaled by another other sources (other ScaledObject or HPA).
+- CPU and/or Memory trigger are used and the scaled workload doesn't have the requests defined. **This rule doesn't apply to all the workload types, only to `Deployment` and `StatefulSet`.**
diff --git a/content/docs/2.10/deploy.md b/content/docs/2.10/deploy.md
@@ -81,16 +81,26 @@ Locate installed KEDA Operator in `keda` namespace, then remove created `KedaCon
 
 If you want to try KEDA on [Minikube](https://minikube.sigs.k8s.io) or a different Kubernetes deployment without using Helm you can still deploy it with `kubectl`.
 
-- We provide sample YAML declaration which includes our CRDs and all other resources in a file which is available on the [GitHub releases](https://github.com/kedacore/keda/releases) page.
+- We provide sample YAML declaration which includes our CRDs and all other resources in a file which is available on the [GitHub releases](https://github.com/kedacore/keda/releases) page. 
+  - We offer two options to deploy KEDA:
+    - Use `keda-2.xx.x.yaml` that includes all features, including [admission webhooks](./concepts/admission-webhooks.md) (recommended)
+    - Use `keda-2.xx.x-core.yaml` that installs the minimal required KEDA components, without admission webhooks
+
 Run the following command (if needed, replace the version, in this case `2.10.0`, with the one you are using):
 
 ```sh
+# Including admission webhooks
 kubectl apply -f https://github.com/kedacore/keda/releases/download/v2.10.0/keda-2.10.0.yaml
+# Without admission webhooks
+kubectl apply -f https://github.com/kedacore/keda/releases/download/v2.10.0/keda-2.10.0-core.yaml
 ```
 
 - Alternatively you can download the file and deploy it from the local path:
 ```sh
-kubectl apply -f keda-2..0.yaml
+# Including admission webhooks
+kubectl apply -f keda-2.10.0.yaml
+# Without admission webhooks
+kubectl apply -f keda-2.10.0-core.yaml
 ```
 
 - You can also find the same YAML declarations in our `/config` directory on our [GitHub repo](https://github.com/kedacore/keda) if you prefer to clone it.
@@ -106,13 +116,19 @@ VERSION=2.10.0 make deploy
 - In case of installing from released YAML file just run the following command (if needed, replace the version, in this case `2.10.0`, with the one you are using):
 
 ```sh
+# Including admission webhooks
 kubectl delete -f https://github.com/kedacore/keda/releases/download/v2.10.0/keda-2.10.0.yaml
+# Without admission webhooks
+kubectl delete -f https://github.com/kedacore/keda/releases/download/v2.10.0/keda-2.10.0-core.yaml
 ```
 
 - If you have downloaded the file locally, you can run:
 
 ```sh
+# Including admission webhooks
 kubectl delete -f keda-2.10.0.yaml
+# Without admission webhooks
+kubectl delete -f keda-2.10.0-core.yaml
 ```
 
 - You would need to run these commands from within the directory of the cloned [GitHub repo](https://github.com/kedacore/keda):

diff --git a/content/docs/2.10/operate/_index.md b/content/docs/2.10/operate/_index.md
@@ -6,7 +6,9 @@ weight = 1
 
 We provide guidance & requirements around various areas to operate KEDA:
 
+- Admission Webhooks ([link](./admission-webhooks))
 - Cluster ([link](./cluster))
-- Integrate with Prometheus ([link](./prometheus))
 - Kubernetes Events ([link](./events))
-- KEDA Metrics Server ([link](./metrics-server))
+- KEDA Metrics Server ([link](./metrics-server))
+- Integrate with Prometheus ([link](./prometheus))
+- Security ([link](./security))
diff --git a/content/docs/2.10/operate/admission-webhooks.md b/content/docs/2.10/operate/admission-webhooks.md
@@ -0,0 +1,9 @@
++++
+title = "Admission Webhooks"
+description = "Admission webhooks configurations guidance"
+weight = 100
++++
+
+## Validation Enforcement
+
+By default, the admission webhooks are registered with `failurePolicy: Ignore`, this won't block the resources creation/update when the admission controller is not available. To ensure that the validation is always required and perform validation, setting `failurePolicy` to `Fail` is required.
diff --git a/content/docs/2.10/operate/cluster.md b/content/docs/2.10/operate/cluster.md
@@ -25,10 +25,11 @@ As a reference, this compatibility matrix shows supported k8s versions per KEDA
 
 The KEDA runtime require the following resources in a production-ready setup:
 
-| Deployment     | CPU                     | Memory                        |
-| -------------- | ----------------------- | ----------------------------- |
-| Metrics Server | Limit: 1, Request: 100m | Limit: 1000Mi, Request: 100Mi |
-| Operator       | Limit: 1, Request: 100m | Limit: 1000Mi, Request: 100Mi |
+| Deployment         | CPU                     | Memory                        |
+| ------------------ | ----------------------- | ----------------------------- |
+| Admission Webhooks | Limit: 1, Request: 100m | Limit: 1000Mi, Request: 100Mi |
+| Metrics Server     | Limit: 1, Request: 100m | Limit: 1000Mi, Request: 100Mi |
+| Operator           | Limit: 1, Request: 100m | Limit: 1000Mi, Request: 100Mi |
 
 These are used by default when deploying through YAML.
 

diff --git a/content/docs/2.10/operate/prometheus.md b/content/docs/2.10/operate/prometheus.md
@@ -1,7 +1,7 @@
 +++
 title = "Integrate with Prometheus"
 description = "Overview of all Prometheus metrics that KEDA provides"
-weight = 200
+weight = 100
 +++
 
 ## Prometheus Exporter Metrics
@@ -19,6 +19,13 @@ The KEDA Operator exposes Prometheus metrics which can be scraped on port `8080`
 - `keda_trigger_totals` - Total number of triggers per trigger type.
 - Metrics exposed by the `Operator SDK` framework as explained [here](https://sdk.operatorframework.io/docs/building-operators/golang/advanced-topics/#metrics).
 
+### Admission Webhooks
+
+The KEDA Webhooks expose Prometheus metrics which can be scraped on port `8080` at `/metrics`. The following metrics are being gathered:
+
+- `scaled_object_validation_total`- The current value for scaled object validations.
+- `scaled_object_validation_errors` - The number of validation errors.
+
 ### Metrics Server
 
 > 💡 **DEPRECATED:** Prometheus Metrics exposed from Metrics Server are deprecated, please consume metrics from KEDA Operator.

diff --git a/content/docs/2.10/operate/security.md b/content/docs/2.10/operate/security.md
@@ -0,0 +1,15 @@
++++
+title = "Security"
+description = "Guidance to configure security options"
+weight = 100
++++
+
+## Use your own TLS Certificates
+
+KEDA uses self-signed certificates for different things. These certificates are generated and rotated by the operator. Certificates are stored in a Kubernetes secret (`kedaorg-certs`) that it's mounted to all KEDA components in the (default) path `/certs`. Generated files are named `tls.crt` and `tls.key` for TLS certificate and `ca.crt` and `ca.key` for CA certificate. KEDA also patches Kubernetes resources to include the `caBundle`, making Kubernetes to trust in the CA.
+
+While this is a good starting point, some end-users may want to use their own certificates which are generated from their own CA in order to improve security. This can be done by disabling the certificate generation/rotation in the operator and updating default values in other components (if required). 
+
+The KEDA operator is responsible for generating certificates for all the services, this behaviour can be disabled removing the console argument `--enable-cert-rotation=true` or setting it to `false`. Once this setting is disabled, user given certs can be placed in the secret `kedaorg-certs` which is automatically mounted in all the components or they can be patched to use other secret (this can be done throught helm values too).
+
+All components inspect the folder `/certs` for any certificates inside it. Argument `--cert-dir` can be used to specify another folder to be used as a source for certificates, this argument can be patched in the manifests or using Helm values. Because these certificates are also used for internal communication between KEDA components, the CA is also required to be registered as a trusted CA inside KEDA components.
diff --git a/content/docs/2.2/concepts/_index.md b/content/docs/2.2/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.3/concepts/_index.md b/content/docs/2.3/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.4/concepts/_index.md b/content/docs/2.4/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.5/concepts/_index.md b/content/docs/2.5/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.6/concepts/_index.md b/content/docs/2.6/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.7/concepts/_index.md b/content/docs/2.7/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.8/concepts/_index.md b/content/docs/2.8/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/content/docs/2.9/concepts/_index.md b/content/docs/2.9/concepts/_index.md
@@ -21,7 +21,7 @@ KEDA performs two key roles within Kubernetes:
 
 The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
 
-![KEDA architecture](/img/keda-arch.png)
+![KEDA architecture](/img/keda-arch-no-webhooks.png)
 
 ### Event sources and scalers
 

diff --git a/schematics.pptx b/schematics.pptx
diff --git a/static/img/keda-arch-no-webhooks.png b/static/img/keda-arch-no-webhooks.png
diff --git a/static/img/keda-arch.png b/static/img/keda-arch.png