docs: add KeptnAppContext ref page; update KeptnApp ref page

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

@@ -4,18 +4,11 @@ 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
+and to work with the corresponding
+[KeptnAppContext](appcontext.md) resource.
 
 ## Synopsis
 
@@ -25,6 +18,8 @@ kind: KeptnApp
 metadata:
   name: <app-name>
   namespace: <application-namespace>
+  labels:
+     app.kubernetes.io/managed-by: keptn
 spec:
   version: "x.y"
   revision: x
@@ -33,14 +28,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
@@ -54,60 +41,42 @@ when the app discovery feature generates the `KeptnApp` resource:
 
 - **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.
+          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**
+    - **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.
+          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.
+            [workload](https://kubernetes.io/docs/concepts/workloads/).
+            Each [workload](https://kubernetes.io/docs/concepts/workloads/)
+            associated with this Keptn application has one entry.
+    - **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 +134,46 @@ 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 the `v1beta1` API version:
+
+- 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 label was not included in `KeptnApp` resources
+  that were created by applying a manifest
+  that had been created manually.
+- If you want to use a `KeptnAppContext` resource with your application,
+  the `name` and `namespace` fields
+  are taken from the annotations of the deployed Kubernetes workloads.
+  The corresponding `KeptnAppContext` resource (if any),
+  must have identical values for these fields.
+- 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 only way to trigger a new execution is to increment
+  the `spec.version` field for the `KeptnApp` resource.
+- The pre/post-deployment tasks and evaluations are now defined in the
+  [KeptnAppContext](appcontext.md)
+  resource rather than in the `KeptnApp` resource.
+
+`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 pre/post-deployment 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,169 @@
+---
+comments: true
+---
+
+# KeptnAppContext
+
+The `KeptnAppContext` custom resource works with the corresponding
+[KeptnApp](app.md) resource
+that has the same name and is located in the same namespace.
+It allows you to
+
+- Add metadata and links to traces for a specific application.
+  This enables you to enrich your traces with additional information that
+  you can use to understand and analyze
+  the performance of your applications.
+
+- Define tasks and evaluations that run
+  before or after the deployment of the `KeptnApp`.
+
+## Synopsis
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: <app-name>
+  namespace: <app-namespace>
+spec:
+  metadata:
+    <custom-attributes>
+  spanLinks:
+  - "<list of links>"
+  preDeploymentTasks:
+  - <list of tasks>
+  postDeploymentTasks:
+  - <list of tasks>
+  preDeploymentEvaluations:
+  - <list of evaluations>
+  postDeploymentEvaluations:
+  - <list of evaluations>
+```
+
+## Fields
+<!-- markdownlint-disable MD007 -->
+
+- **apiVersion** -- API version being used
+   Must be set to `lifecycle.keptn.sh/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 `KeptnApp` resource.
+- **spec**
+     - **metadata** -- list of key-value pairs
+       that are propagated to the application trace as attributes.
+       For example, the following lines add the `commit-id`
+       and `author` information to the `KEPTN_CONTEXT`
+       of the workload or `KeptnApp` where it is specified:
+
+          ```yaml
+          spec:
+            metadata:
+              commit-id: "1234"
+              author: "myUser"
+          ```
+
+     - **spanLinks** -- List of OpenTelemetry span links
+    that connect multiple traces.
+    For example, this can be used to connect
+    deployments of the same application
+    through different stages.
+    You can retrieve the value to use
+    from the JSON representation of the trace in Jaeger.
+    The structure of this is:
+
+          ```yaml
+          00-<trace-id>-<span-id>-01
+          ```
+
+          After you add this field to your `KeptnAppContext` manifest,
+          you must increment the `revision` number
+          of the corresponding `KeptnApp` resource
+          and apply the manifest to store the information in the traces.
+
+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
+
+`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 each 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.
+
+## 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