docs: move webhook section from README to docs

README.md

@@ -173,6 +173,8 @@ For more info about Keptn, please see our
   and implement its various features.
 - [Architecture](https://lifecycle.keptn.sh/docs/concepts/architecture/) provides detailed technical information
   about how Keptn works.
+- [Components](https://keptn.sh/stable/docs/components/) provides an overview
+  about Keptn components.
 - [CRD Reference](https://lifecycle.keptn.sh/docs/yaml-crd-ref/) and
   [API Reference](https://lifecycle.keptn.sh/docs/crd-ref/)
   provide detailed reference material for the custom resources
@@ -186,82 +188,6 @@ about Keptn on the
 Videos that refer to the "Keptn Lifecycle Controller"
 are relevant for the Keptn project.
 
-### Webhook
-
-Annotating a namespace subjects it to the effects of the mutating webhook:
-
-```yaml
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: podtato-kubectl
-  annotations:
-    keptn.sh/lifecycle-toolkit: "enabled"  # this line tells the webhook to handle the namespace
-```
-
-The mutating webhook only modifies specifically annotated resources in the annotated namespace.
-When the webhook receives a request for a new pod,
-it looks for the workload annotations:
-
-```yaml
-keptn.sh/workload: "some-workload-name"
-```
-
-The mutation consists in changing the scheduler used for the deployment
-with the Keptn Scheduler.
-The webhook then creates a workload and app resource per annotated resource.
-You can also specify a custom app definition with the annotation:
-
-```yaml
-keptn.sh/app: "your-app-name"
-```
-
-In this case the webhook does not generate an app,
-but it expects that the user will provide one.
-Additionally, it computes a version string,
-using a hash function that takes certain properties of the pod as parameters
-(e.g. the images of its containers).
-Next, it looks for an existing instance of a `Workload CRD`
-for the specified workload name:
-
-- If it finds the `Workload`,
-  it updates its version according to the previously computed version string.
-  In addition, it includes a reference to the ReplicaSet UID of the pod
-  (i.e. the Pods owner),
-  or the pod itself, if it does not have an owner.
-- If it does not find a workload instance,
-  it creates one containing the previously computed version string.
-  In addition, it includes a reference to the ReplicaSet UID of the pod
-  (i.e. the Pods owner), or the pod itself, if it does not have an owner.
-
-It uses the following annotations for the specification
-of the pre/post deployment checks that should be executed for the `Workload`:
-
-- `keptn.sh/pre-deployment-tasks: task1,task2`
-- `keptn.sh/post-deployment-tasks: task1,task2`
-
-and for the Evaluations:
-
-- `keptn.sh/pre-deployment-evaluations: my-evaluation-definition`
-- `keptn.sh/post-deployment-evaluations: my-eval-definition`
-
-After either one of those actions has been taken,
-the webhook sets the scheduler of the pod
-and allows the pod to be scheduled.
-
-### Scheduler
-
-After the Webhook mutation, the Keptn-Scheduler handles the annotated resources.
-The scheduling flow follows the default
-[scheduler](https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/)
-behavior,
-since it implements a scheduler plugin based on the
-[scheduling framework]( https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/).
-For each pod, at the very end of the scheduling cycle,
-the plugin verifies that the pre deployment checks have terminated
-by retrieving the current status of the WorkloadInstance.
-Only when that is successful is the pod bound to a node.
-
 ## Contributing
 
 For more information about contributing to Keptn, please

docs/docs/components/lifecycle-operator/webhook.md

@@ -0,0 +1,75 @@
+---
+comments: true
+---
+
+# Mutating Webhook
+
+Keptn uses
+[Admission Webhooks](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks)
+to mutate resources.
+To enable the webhook (and therefore Keptn Lifecycle Management)
+for a certain namespace, the namespace must be annotated:
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: podtato-kubectl
+  annotations:
+    keptn.sh/lifecycle-toolkit: "enabled"  # this line tells the webhook to handle the namespace
+```
+
+The mutating webhook only modifies specifically annotated resources in the annotated namespace.
+When the webhook receives a request for a new pod, it first either replaces the scheduler
+with the Keptn Scheduler, or adds the
+[Scheduling Gate](https://keptn.sh/stable/docs/components/scheduling/#keptn-scheduling-gates-for-k8s-127-and-above).
+
+In the next step it looks for the workload annotations:
+
+```yaml
+keptn.sh/workload: "some-workload-name"
+keptn.sh/version: "some-workload-version"
+```
+
+If the `keptn.sh/version` annotation is missing, the webhook computes a version string,
+using a hash function that takes certain properties of the pod as parameters
+(e.g. the images of its containers).
+Next, it looks for an existing instance of a `KeptnWorkload`
+for the specified workload name:
+
+- If it finds the `KeptnWorkload`,
+  it updates its version according to the previously computed version string.
+  In addition, it includes a reference to the ReplicaSet UID of the pod
+  (i.e. the Pods owner).
+- If it does not find a workload instance,
+  it creates one containing the previously computed version string.
+
+Afterwards the webhook looks for the application annotation:
+
+```yaml
+keptn.sh/app: "your-app-name"
+```
+
+The webhook searches for the `KeptnAppCreationRequest` resource with the name stored in the `keptn.sh/app`
+annotations.
+If it doesn't find it, it creates it and the automatic creation of the `KeptnApp` is afterwards
+handled by the `KeptnAppCreationRequest Controller`.
+
+The `keptn.sh/app` annotation is not mandatory for single-service applications.
+If you have a multi-service application, you must add it to all workloads
+to define which workloads belong to the application.
+
+The Pod can also contain information about the definition of pre or
+post-deployment tasks or evaluations for each workload.
+These are specified via these annotations:
+
+- `keptn.sh/pre-deployment-tasks: task1,task2`
+- `keptn.sh/post-deployment-tasks: task1,task2`
+
+and for the Evaluations:
+
+- `keptn.sh/pre-deployment-evaluations: my-evaluation-definition`
+- `keptn.sh/post-deployment-evaluations: my-eval-definition`
+
+The lists of tasks or evaluations are parsed and stored in the `KeptnWorkload`
+resource created in the previous steps.

mkdocs.yml

@@ -152,6 +152,7 @@ nav:
               - Flow of deployment: docs/components/lifecycle-operator/deployment-flow.md
               - Keptn Applications and Keptn Workloads: docs/components/lifecycle-operator/keptn-apps.md
               - Keptn non-blocking application deployment: docs/components/lifecycle-operator/keptn-non-blocking.md
+              - Webhooks: docs/components/lifecycle-operator/webhook.md
           - Metrics Operator: docs/components/metrics-operator.md
           - Scheduler and Scheduling Gates: docs/components/scheduling.md
           - Keptn Certificate Manager: docs/components/certificate-operator.md