docs: improve how-to and ref info about integrating KLT with apps

docs/content/en/docs/concepts/architecture/keptn-apps/_index.md

@@ -0,0 +1,83 @@
+---
+title: KeptnApp and KeptnWorkload resources
+linktitle: Keptn Applications and Keptn Workloads
+description: How Keptn applications work
+weight: 50
+cascade:
+---
+
+## Keptn Workloads
+
+A
+[KeptnWorkload](../../../crd-ref/lifecycle/v1alpha3/#keptnworkload)
+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.
+
+In its state, it keeps track of the currently active `Workload Instances`,
+(`Pod`, `DaemonSet`, `StatefulSet`, and `ReplicaSet` resources),
+as well as the overall state of the Pre Deployment phase,
+which the scheduler can use to determine whether the pods belonging to a workload should proceed.
+When it detects that the referenced object has reached its desired state
+(e.g. all pods of a deployment are up and running),
+it knows that a`PostDeploymentCheck` can be triggered.
+
+The KeptnWorkload resources are created automatically
+by the mutating webhook as soon as a pod for the workload
+(i.e. `Deployment`, `StatefulSet`, `DaemonSet`, `ReplicaSet`)
+is about to be started.
+The KeptnWorkloads are created automatically and without delay by the webhook.
+
+## Keptn Applications
+
+A [KeptnApp](../../../yaml-crd-ref/app.md)
+resource combines multiple Kubernetes
+[workloads](https://kubernetes.io/docs/concepts/workloads/)
+into a single entity
+that represent the application that is published.
+Note that the Kubernetes documentation
+often refers to workloads as applications,
+but each workload actually corresponds to one version
+of one deployable microservice,
+not the amalgamation of multiple microservices
+that typically comprise the released software.
+
+Implementing Keptn applications provides the following benefits:
+
+* Observability tools report on the deployment
+  of all workloads together rather than individually.
+* You can define pre-deployment evaluations and tasks
+  that must all complete successfully
+  before the scheduler creates the pods for any of the workloads.
+* You can define post-deployment evaluations and tasks
+  that run only after all the workloads have completed successfully.
+
+You control the content of a `KeptnApp` resource
+with annotations or labels that are applied to each
+[Workload](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/):
+
+* The annotations described in
+  [Basic annotations](../../../implementing/integrate/#basic-annotations)
+  are used to automatically generate `KeptnApp` resources
+  that contain the identifications required
+  to run the KLT observability features.
+* You must manually add the annotations described in
+  [Pre- and post-deployment checks](../../../implementing/integrate/#pre--and-post-deployment-checks)
+  to the basic `KeptnApp` manifest to define
+  the evaluations and tasks you want to run pre- and post-deployment.
+
+By default, the `KeptnApp` resources are updated every 30 seconds
+when any of the Workloads have been modified;
+The timeout is provided because it may take some time
+to apply all `KeptnWorkload` resources to the cluster.
+This interval can be modified for the cluster by changing the value
+of the `keptnAppCreationRequestTimeoutSeconds` field in the
+[KeptnConfig](../../../yaml-crd-ref/config.md)
+resource.

docs/content/en/docs/getting-started/observability/_index.md

@@ -70,23 +70,14 @@ you need to do the following:
    [Install and update](../../install)
    to install and enable KLT on your cluster.
 1. Follow the instructions in
-   [Integrate KLT with your applications](../../implementing/integrate)
-   to integrate KLT with your Kubernetes cluster.
-   This requires the following:
-
-   - Follow the instructions in
-     [Annotate workload](../../implementing/integrate/#basic-annotations)
-     to integrate the Lifecycle Toolkit into your Kubernetes cluster
-     by applying basic annotations
-     to your workload and pod resources.
-   - Follow the instructions in
-     [Define a Keptn application](../../implementing/integrate/#define-a-keptn-application)
-     to create a Keptn application that aggragates
-     all the `workloads` for your deployment into a single
-     [KeptnApp](../../yaml-crd-ref/app.md) resource.
-     For this exercise, we recommend that you use
-     [Keptn automatic app discovery](../../implementing/integrate/#use-keptn-automatic-app-discovery)
-     to automatically generate a Keptn Application.
+   [Basic annotations](../../implementing/integrate/#basic-annotations)
+   to integrate the Lifecycle Toolkit into your Kubernetes cluster
+   by applying basic annotations
+   to your workload and pod resources.
+   and to create appropriate
+   [KeptnApp](../../yaml-crd-ref/app.md)
+   resources that aggragate
+   all the `workloads` for a logical deployment into a single resource.
 
 ## DORA metrics
 

docs/content/en/docs/getting-started/orchestrate/_index.md

@@ -77,22 +77,14 @@ you need to do the following:
    [Install and update](../../install)
    to install and enable KLT on your cluster.
 1. Follow the instructions in
-   [Integrate KLT with your applications](../../implementing/integrate)
-   to integrate KLT with your Kubernetes cluster:
-
-   * Follow the instructions in
-     [Annotate workload](../../implementing/integrate/#basic-annotations)
-     to integrate the Lifecycle Toolkit into your Kubernetes cluster
-     by applying basic annotations to your `Deployment` resource.
-   * Follow the instructions in
-     [Define a Keptn application](../../implementing/integrate/#define-a-keptn-application)
-     to create a
-     [KeptnApp](../../yaml-crd-ref/app.md) resource
-     that includes all workloads on the cluster,
-     regardless of the tools being used.
-     For this exercise, we recommend that you
-     [Use Keptn automatic app discovery](../../implementing/integrate/#use-keptn-automatic-app-discovery)
-     to automatically generate a Keptn Application.
+   [Annotate workload](../../implementing/integrate/#basic-annotations)
+   to integrate the Lifecycle Toolkit into your Kubernetes cluster
+   by applying basic annotations to your `Deployment` resource.
+   This also creates appropriate
+   [KeptnApp](../../yaml-crd-ref/app.md) resources
+   that aggregates workloads that are combined
+   into the released product,
+   regardless of the tools being used.
 
 ## Define evaluations to be performed pre- and post-deployment