docs: add KeptnAppContext ref page; update KeptnApp ref page

docs/docs/reference/crd-reference/app.md

@@ -4,18 +4,13 @@ comments: true
 
 # KeptnApp
 
-A `KeptnApp` resource lists all the [workloads](https://kubernetes.io/docs/concepts/workloads/)
-that constitute a logical application.
-It contains information about:
-
-- All [workloads](https://kubernetes.io/docs/concepts/workloads/) and checks
-  that are associated with a Keptn application
-- A list of tasks and evaluations to be executed
-  pre- and post-deployment.
-- Tasks referenced by `KeptnApp` are defined in a
-  [KeptnTaskDefinition](taskdefinition.md) resource.
-  `KeptnApp` identifies the task by the value of the `metadata.name` field
-  and does not need to understand what runner is used to define the task.
+A `KeptnApp` resource is auto-generated to list all the
+[workloads](https://kubernetes.io/docs/concepts/workloads/)
+that constitute a logical Keptn application.
+
+If you are using the context propagation feature,
+Keptn auto-generates the `KeptnApp` resource to work with the corresponding
+[KeptnAppContext](appcontext.md) resource.
 
 ## Synopsis
 
@@ -25,6 +20,9 @@ kind: KeptnApp
 metadata:
   name: <app-name>
   namespace: <application-namespace>
+  labels:
+     my-custom-label: <label-name>
+     app.kubernetes.io/managed-by: keptn
 spec:
   version: "x.y"
   revision: x
@@ -33,14 +31,6 @@ spec:
     version: <version-string>
   - name: <workload2-name>
     version: <version-string>
-  preDeploymentTasks:
-  - <list of tasks>
-  postDeploymentTasks:
-  - <list of tasks>
-  preDeploymentEvaluations:
-  - <list of evaluations>
-  postDeploymentEvaluations:
-  - <list of evaluations>
 ```
 
 ## Fields
@@ -53,61 +43,45 @@ when the app discovery feature generates the `KeptnApp` resource:
    Must be set to `KeptnApp`
 
 - **metadata**
-  - **name** -- Unique name of this application.
-    Names must comply with the
-    [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
-    specification.
-  - **namespace** -- Namespace of this application.
-
+     - **name** -- Unique name of this application.
+          Names must comply with the
+          [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
+          specification.
+          This value is the `name` assigned to the
+          `keptn.sh/app` or `app.kubernetes.io/part-of`
+          label or annotation for the workloads included in this `KeptnApp`.
+          If a `KeptnAppContext` resource is associated with this resource,
+          it must have the same `name` as this `KeptnApp`.
+     - **namespace** -- Namespace of this application.
+          If a `KeptnAppContext` resource is associated with this resource,
+          it must have the same `namespace` as this `KeptnApp`.
+     - **labels**
+          - **my-custom-label** -- NEED DESCRIPTION
+          - **app-kubernetes.io/managed-by:keptn** --
+            tells Keptn that this resource was autogenerated,
+            which is always the case for the `v1beta1` version.
 - **spec**
-  - **version** (required) -- version of the Keptn application.
-    Changing this version number causes a new execution
-    of all application-level checks
-  - **revision** -- revision of a `version`.
-    The value is an integer that can be modified
-    to trigger another deployment of a `KeptnApp` of the same version.
-    For example, increment this number to restart a `KeptnApp` version
-    that failed to deploy, perhaps because a
-    `preDeploymentEvaluation` or `preDeploymentTask` failed.
-    See
-    [Restart an Application Deployment](../../guides/restart-application-deployment.md)
-    for a longer discussion of this.
-  - **workloads**
-    - **name** (required) -- name of this Kubernetes
-      [workload](https://kubernetes.io/docs/concepts/workloads/).
-      Use the same naming rules listed above for the application name.
-      Provide one entry for each [workload](https://kubernetes.io/docs/concepts/workloads/)
-      associated with this Keptn application.
-    - **version** (required) -- version number for this [workload](https://kubernetes.io/docs/concepts/workloads/).
-      Changing this number causes a new execution
-      of checks for this [workload](https://kubernetes.io/docs/concepts/workloads/) only,
-      not the entire application.
-
-The remaining fields are required only when implementing
-the release lifecycle management feature.
-If used, these fields must be populated manually:
-
-- **preDeploymentTasks** -- list each task
-    to be run as part of the pre-deployment stage.
-    Task names must match the value of the `metadata.name` field
-    for the associated [KeptnTaskDefinition](taskdefinition.md) resource.
-- **postDeploymentTasks** -- list each task
-    to be run as part of the post-deployment stage.
-    Task names must match the value of the `metadata.name` field
-    for the associated
-    [KeptnTaskDefinition](taskdefinition.md)
-    resource.
-- **preDeploymentEvaluations** -- list each evaluation to be run
-    as part of the pre-deployment stage.
-    Evaluation names must match the value of the `metadata.name` field
-    for the associated
-    [KeptnEvaluationDefinition](evaluationdefinition.md)
-    resource.
-- **postDeploymentEvaluations** -- list each evaluation to be run
-    as part of the post-deployment stage.
-    Evaluation names must match the value of the `metadata.name` field
-    for the associated [KeptnEvaluationDefinition](evaluationdefinition.md)
-    resource.
+     - **version** (required) -- version of the Keptn application.
+     - **revision** -- revision of a `version`.
+          The value is an integer that can be modified
+          to trigger another deployment of a `KeptnApp` of the same version.
+          For example, increment this number to restart a `KeptnApp` version
+          that failed to deploy, perhaps because a
+          `preDeploymentEvaluation` or `preDeploymentTask` failed.
+          See
+          [Restart an Application Deployment](../../guides/restart-application-deployment.md)
+          for a longer discussion of this.
+     - **workloads**
+        - **name** (required) -- name of this Kubernetes
+            [workload](https://kubernetes.io/docs/concepts/workloads/).
+            Use the same naming rules listed above for the application name.
+            Provide one entry for each [workload](https://kubernetes.io/docs/concepts/workloads/)
+            associated with this Keptn application.
+        - **version** (required) -- version number for this
+            [workload](https://kubernetes.io/docs/concepts/workloads/).
+            Changing this number causes a new execution
+            of checks for this [workload](https://kubernetes.io/docs/concepts/workloads/) only,
+            not the entire application.
 
 ## Usage
 
@@ -165,14 +139,43 @@ spec:
 
 ## Differences between versions
 
-- The `spec.revision` field is introduced in v1alpha2.
-- The pre/post-deployment tasks and evaluations are not
-supported anymore in v1beta1.
+The synopsis of the `KeptnApp` resource
+is changed in `v1beta1` library:
+
+- The `apiVersion` field now references the `v1beta1` version
+  of the `lifecycle.keptn.sh` API.
+- `KeptnApp` is
+  [autogenerated](../../guides/auto-app-discovery.md);
+  you cannot create it manually by applying a manifest.
+- The `app.kubernetes.io/managed-by: keptn` label or annotation
+  is always used for the `v1beta1` library
+  because the `KeptnApp` resource is always autogenerated.
+  In earlier releases, this field was not included in `KeptnApp` resources
+  that were created by applying a manifest
+  that had been created manually.
+- If you are using the context propagation feature,
+  the `name` and `namespace` fields
+  and must have identical values to those
+  in the corresponding `KeptnAppContext` resource.
+- The `metadata.version` field is now completely managed by Keptn.
+  You do not increment this value to cause
+  a new execution of tasks and evaluations.
+- The pre/post-deployment tasks and evaluations are now defined in the
+  [KeptnAppContext](appcontext.md)
+  resource rather than in `KeptnApp`.
+
+`KeptnApp` resources that were completely autogenerated
+for earlier versions are converted automatically to the new structure.
+You must manually migrate older `KeptnApp` resources
+that were created manually
+or that were manually edited
+to add `preDeployment` and `postDeployment tasks and evaluations.
 For more information please refer
 to the [migration section](../../migrate/keptnapp/index.md).
 
 ## See also
 
+- [KeptnAppContext](appcontext.md)
 - [KeptnTaskDefinition](taskdefinition.md)
 - [KeptnEvaluationDefinition](evaluationdefinition.md)
 - [Deployment tasks](../../guides/tasks.md)

docs/docs/reference/crd-reference/appcontext.md

@@ -0,0 +1,125 @@
+---
+comments: true
+---
+
+# KeptnAppContext
+
+(Need to add description)
+
+It works with the corresponding
+[KeptnApp](app.md) resource
+that has the same name and is located in the same namespace.
+
+`KeptnAppContext` lists the tasks and evaluations
+to be executed pre/post-deployment.
+Tasks referenced by `KeptnAppContext` are defined in a
+[KeptnTaskDefinition](taskdefinition.md)
+resource.
+`KeptnAppContext` identifies the task by the value of the `metadata.name` field
+and does not need to understand what runner is used to define the task.
+Similarly, evaluations referenced are defined in a
+[KeptnEvaluationDefinition](evaluationdefinition.md)
+resource and identified by the value of the `metadata.name` field;
+`KeptnAppContext` does not need to understand
+the data source or query being used for the evaluation.
+
+## Synopsis
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: <app-name>
+  namespace: <app-namespace>
+spec:
+  preDeploymentTasks:
+  - <list of tasks>
+  postDeploymentTasks:
+  - <list of tasks>
+  preDeploymentEvaluations:
+  - <list of evaluations>
+  postDeploymentEvaluations:
+  - <list of evaluations>
+  ...
+```
+
+## Fields
+
+* **apiVersion** -- API version being used
+   Must be set to `v1beta1`
+* **kind** -- Resource type
+   Must be set to `KeptnAppContext`
+* **metadata**
+  * **name** -- Unique name of this `KeptnAppContext` resource.
+       Names must comply with the
+       [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
+       specification
+       and match the `name` given to the associated `KeptnApp` resource..
+  * **namespace** -- Namespace of this application.
+       This must match the `namespace` given to
+       the associated `KeptnAp` resource.
+
+The remaining fields are required only when implementing
+the release lifecycle management feature.
+If used, these fields must be populated manually:
+
+* **spec**
+
+  * **preDeploymentTasks** -- list each task
+        to be run as part of the pre-deployment stage.
+        Task names must match the value of the `metadata.name` field
+        for the associated [KeptnTaskDefinition](taskdefinition.md) resource.
+  * **postDeploymentTasks** -- list each task
+        to be run as part of the post-deployment stage.
+        Task names must match the value of the `metadata.name` field
+        for the associated
+        [KeptnTaskDefinition](taskdefinition.md)
+        resource.
+  * **preDeploymentEvaluations** -- list each evaluation to be run
+        as part of the pre-deployment stage.
+        Evaluation names must match the value of the `metadata.name` field
+        for the associated
+        [KeptnEvaluationDefinition](evaluationdefinition.md)
+        resource.
+  * **postDeploymentEvaluations** -- list each evaluation to be run
+        as part of the post-deployment stage.
+        Evaluation names must match the value of the `metadata.name` field
+        for the associated [KeptnEvaluationDefinition](evaluationdefinition.md)
+        resource.
+
+## Usage
+
+## Example
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: podtato-head
+  namespace: podtato-kubectl
+spec:
+  preDeploymentTasks:
+    - container-sleep
+    - python-secret
+```
+
+## Files
+
+[KeptnAppContext](../api-reference/lifecycle/v1beta1/index.md#keptnappcontext)
+
+## Differences between versions
+
+The `KeptnAppContext` resource is new in the `v1beta1` version
+of the lifecycle operator.
+
+## See also
+
+* [KeptnApp](app.md)
+* [KeptnTaskDefinition](taskdefinition.md)
+* [KeptnEvaluationDefinition](evaluationdefinition.md)
+* [Deployment tasks](../../guides/tasks.md)
+* [Architecture of KeptnWorkloads and KeptnTasks](../../components/lifecycle-operator/keptn-apps.md)
+* Getting started with
+  [Release Lifecycle Management](../../getting-started/lifecycle-management.md)
+* [Use Keptn automatic app discovery](../../guides/auto-app-discovery.md)
+* [Restart an Application Deployment](../../guides/restart-application-deployment.md)

mkdocs.yml

@@ -160,6 +160,7 @@ nav:
               - AnalysisDefinition: docs/reference/crd-reference/analysisdefinition.md
               - AnalysisValueTemplate: docs/reference/crd-reference/analysisvaluetemplate.md
               - KeptnApp: docs/reference/crd-reference/app.md
+              - KeptnAppContext: docs/reference/crd-reference/appcontext.md
               - KeptnConfig: docs/reference/crd-reference/config.md
               - KeptnEvaluationDefinition: docs/reference/crd-reference/evaluationdefinition.md
               - KeptnMetric: docs/reference/crd-reference/metric.md