docs: restructure info on tasks and evaluations (#2639)

Signed-off-by: Meg McRoberts <[email protected]> Signed-off-by: Moritz Wiesinger <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]>
keptn · Dec 20, 2023 · aa1abf0 · aa1abf0
1 parent a5ff5e7
commit aa1abf0
Show file tree

Hide file tree

Showing 15 changed files with 457 additions and 367 deletions.
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
@@ -489,7 +489,6 @@ prebuilt
 Predeployment
 PREDEPLOYMENTEVALUATIONSTATUS
 PREDEPLOYMENTSTATUS
-prepost
 prepostdeployment
 prepostevaluation
 previewer

diff --git a/docs-new/docs/components/lifecycle-operator/keptn-apps.md b/docs-new/docs/components/lifecycle-operator/keptn-apps.md
@@ -7,8 +7,8 @@ A
 resource augments a Kubernetes
 [Workload](https://kubernetes.io/docs/concepts/workloads/)
 with the ability to handle extra phases.
-It can execute the pre- and post-deployment evaluations of a Workload
-and run pre- and post-deployment tasks.
+It can execute the pre/post-deployment evaluations of a Workload
+and run pre/post-deployment tasks.
 
 In its state, it tracks the currently active `Workload Instances`,
 (`Pod`, `DaemonSet`, `StatefulSet`, and `ReplicaSet` resources),
@@ -64,9 +64,9 @@ for the `KeptnApp` resource itself:
   that contain the identifications required
   to run the Keptn observability features.
 * You must manually add the annotations described in
-  [Pre- and post-deployment checks](../../guides/integrate.md#prepost-deployment-checks)
+  [Annotations to KeptnApp](../../guides/tasks.md#annotations-to-keptnapp)
   to the basic `KeptnApp` manifest to define
-  the evaluations and tasks you want to run pre- and post-deployment.
+  the evaluations and tasks you want to run pre/post-deployment.
 
 The `KeptnApp` resources that are generated automatically
 contain the identifications required to run the Keptn observability features.

diff --git a/docs-new/docs/getting-started/lifecycle-management.md b/docs-new/docs/getting-started/lifecycle-management.md
@@ -1,7 +1,7 @@
 # Release Lifecycle Management
 
 The Release Lifecycle Management tools run
-pre- and post-deployment tasks and checks
+pre/post-deployment tasks and checks
 for your existing cloud-native deployments
 to make them more robust.
 This tutorial introduces these tools.
@@ -15,11 +15,12 @@ exercise.
 
 When Keptn is successfully monitoring your deployments, it can also run arbitrary tasks and SLO evaluations:
 
-- pre-deployment (before the pod is scheduled) and
-- post-deployment (after the post is scheduled)
+- pre-deployment (before the Pod is scheduled)
+- post-deployment (after the Pod is scheduled)
 
-> Pre and post deployments can also run on a KeptnApp level.
-> See [annotations to KeptnApp](../guides/integrate.md#annotations-to-keptnapp)
+> Tasks and Evaluations can also run on a KeptnApp level.
+  See
+  [Annotations to KeptnApp](../guides/tasks.md#annotations-to-keptnapp).
 
 ## Prerequisites: Deploy webhook sink
 
@@ -51,7 +52,7 @@ Open a browser and go to `http://localhost:8084`
 
 You should see a page like this with a unique URL (your ID will be different).
 
-![webhook.site page](./assets/webhook.site.1.png)
+![webhook.site page](assets/webhook.site.1.png)
 
 Make a note of that unique URL.
 
@@ -62,7 +63,7 @@ The page should remain blank, but when toggling back to `http://localhost:8084`,
 
 Every request sent to that unique URL will be logged here.
 
-![webhook.site entry](./assets/webhook.site.2.png)
+![webhook.site entry](assets/webhook.site.2.png)
 
 ## Add a Post Deployment Task
 
@@ -134,7 +135,7 @@ runsendevent1-*****   1/1           6s         2m
 
 The webhook sync should show this:
 
-![webhook sync](./assets/webhook.site.3.png)
+![webhook sync](assets/webhook.site.3.png)
 
 Incidentally, this is exactly how you can use Keptn with [applications deployed outside of Kubernetes](../use-cases/non-k8s.md).
 
@@ -214,8 +215,10 @@ Do this by using the `keptn.sh/pre-deployment-tasks` label.
 
 ## Further Information
 
-There is a lot more you can do with KeptnTasks.
-See [pre and post deployment checks page](../guides/integrate.md#prepost-deployment-checks) to find out more.
+You can do a lot more with KeptnTasks.
+See the
+[Deployment tasks](../guides/tasks.md)
+guide for more information.
 
 ## What's next?
 

diff --git a/docs-new/docs/guides/evaluations.md b/docs-new/docs/guides/evaluations.md
@@ -1,5 +1,58 @@
 # Evaluations
 
+A `KeptnEvaluation` does a simple evaluation of the metrics data you capture,
+to answer a question such as "Do I have more than four CPUs available?"
+or "Is my remote database accessible?"
+or check for other problems in your infrastructure.
+It can be defined to run before or after your software is deployed.
+
+When an evaluation is run pre-deployment,
+the deployment is kept in a pending state
+until the evaluation passes with a successful result.
+
+Use the
+[Analysis](slo.md)
+feature if you want to do more complex investigations
+that may include multiple criteria with weights and scoring applied.
+
+To implement evaluations, you must:
+
+1. [Install and enable Keptn](../installation/index.md)
+   in your cluster.
+   You will need both the
+   Keptn Metrics Operator (`metrics-operator`)
+   and the Keptn Lifecycle Operator (`lifecycle-operator`)
+   [components](../components/index.md).
+1. Define a
+   [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md)
+   resource for each data source you want to use for evaluations.
+   You can define multiple instances of multiple types of data providers.
+1. Annotate all
+   [workloads](https://kubernetes.io/docs/concepts/workloads/)
+   ([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
+   [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/),
+   [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/),
+   and
+   [ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/))
+   with
+   [basic annotations](integrate.md#basic-annotations).
+1. Generate the required
+   [KeptnApp](../reference/crd-reference/app.md)
+   resources following the instructions in
+   [Auto app discovery](auto-app-discovery.md).
+1. Define a
+   [KeptnMetric](../reference/crd-reference/metric.md)
+   resource for each piece of data
+   (defined as a query from one of your data sources)
+   that you need for your evaluations.
+1. [Create KeptnEvaluationDefinition](#create-keptnevaluationdefinition-resources)
+   resources for each evaluation you want to perform.
+1. Manually edit the appropriate `KeptnApp` resources
+   to annotate them for each `KeptnEvaluationDefinition` resource
+   you want to run pre- and/or post-deployment.
+
+## Create KeptnEvaluationDefinition resources
+
 A
 [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
 resource contains a list of `objectives`,
@@ -28,27 +81,6 @@ file:
 {% include "../assets/crd/metric.yaml" %}
 ```
 
-To run an evaluation on one of your
-[Workloads](https://kubernetes.io/docs/concepts/workloads/)
-([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
-[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/),
-[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/),
-or
-[ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/),
-you must:
-
-* Annotate your [workloads](https://kubernetes.io/docs/concepts/workloads/)
-  to identify the `KeptnEvaluationDefinition` resource you want to run
-  pre- and post-deployment for the specific [workloads](https://kubernetes.io/docs/concepts/workloads/).
-* Manually edit all
-  [KeptnApp](../reference/crd-reference/app.md) resources
-  to specify the `KeptnEvaluationDefinition` to be run
-  pre- and post-deployment evaluations for the `KeptnApp` itself.
-
-See
-[Pre- and post-deployment checks](./integrate.md#prepost-deployment-checks)
-for details.
-
 Note the following:
 
 * One `KeptnEvaluationDefinition` resource can include
@@ -72,3 +104,59 @@ Note the following:
   is written to a
   [KeptnEvaluation](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnevaluation)
   resource.
+
+## Annotate the KeptnApp resource
+
+To define the pre/post-deployment evaluations to run,
+you must manually edit the
+[KeptnApp](../reference/crd-reference/app.md)
+YAML file to provide an annotation
+for each `KeptnEvaluationDefinition` resource to be run
+pre/post-deployment.
+The annotations for evaluations are:
+
+```yaml
+keptn.sh/pre-deployment-evaluations: <evaluation-name>
+keptn.sh/post-deployment-evaluations: <evaluation-name>
+```
+
+   > **Caveat:** Be very careful when implementing pre-deployment evaluations
+     since, if one fails, Keptn prevents the Deployment from running.
+   >
+
+The value of these annotations corresponds
+to the values of the `name` field of each
+[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md)
+resource.
+These resources contain re-usable "functions"
+that can execute before and after the deployment.
+
+If everything is fine, the deployment continues.
+
+## Example of pre/post-deployment actions
+
+A comprehensive example of pre/post-deployment
+evaluations and tasks can be found in our
+[examples folder](https://github.com/keptn/lifecycle-toolkit/tree/main/examples/sample-app),
+where we use [Podtato-Head](https://github.com/podtato-head/podtato-head)
+to run some simple pre-deployment checks.
+
+To run the example, download the example
+then issue the following commands:
+
+```shell
+cd ./examples/podtatohead-deployment/
+kubectl apply -f .
+```
+
+Afterward, use the following command
+to monitor the status of the deployment:
+
+```shell
+kubectl get keptnworkloadversion -n podtato-kubectl -w
+```
+
+The deployment for a workload stays in a `Pending` state
+until the respective pre-deployment check is successfully completed.
+Afterwards, the deployment starts and when the workload is deployed,
+the post-deployment checks start.