docs: edits/xrefs for keptnapp migration (#2944)

Signed-off-by: Meg McRoberts <[email protected]> Co-authored-by: RealAnna <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]>
keptn · Feb 5, 2024 · 45a56d1 · 45a56d1
1 parent 882b442
commit 45a56d1
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 30 deletions.
diff --git a/docs/docs/migrate/keptnapp/assets/keptnapp-migrated.yaml b/docs/docs/migrate/keptnapp/assets/keptnapp-migrated.yaml
@@ -1,4 +1,4 @@
-apiVersion: lifecycle.keptn.sh/v1alpha3
+apiVersion: lifecycle.keptn.sh/v1beta1
 kind: KeptnApp
 metadata:
   name: "some-keptn-app"

diff --git a/docs/docs/migrate/keptnapp/index.md b/docs/docs/migrate/keptnapp/index.md
@@ -1,40 +1,49 @@
 # Migrating KeptnApp to KeptnAppContext
 
-The introduction of the `KeptnAppContext` resource
-in Keptn v0.11.0
-requires modifications to existing
+The
+[KeptnAppContext](../../reference/crd-reference/appcontext.md)
+resource is new in the `v1beta1` API version.
+Existing
 [KeptnApp](../../reference/crd-reference/app.md)
-resources that were generated manually.
+resources that were generated manually must be migrated
+because of this new feature.
 This page gives instructions for doing that.
 
+> **Note**
+> Manual migration is only required for:
+>
+> * Manually created `KeptnApp` resources
+> * Automatically created `KeptnApp` resources with
+>   manually edited pre/post-deployment tasks or evaluations**
+>
+> `KeptnApp` resources created using the
+> [automatic app-discovery](../../guides/auto-app-discovery.md)
+> feature without any manual changes in the pre/post-deployment
+> tasks/evaluations section do not require any action.
+
 ## Migration steps
 
-> **Warning**
-Migration is only required for
-**manually created KeptnApp** or
-automatically created `KeptnApp` resources with
-**manually edited pre/post-deployment tasks or evaluations**.
-`KeptnApp` resources created by Keptn via the
-[automatic app-discovery](../../guides/auto-app-discovery.md)
-without any manual changes in the pre/post-deployment
-tasks/evaluations section do not require any action.
-
-To migrate an existing **manually created KeptnApp** or
-automatically created `KeptnApp` with
-**manually edited pre/post-deployment tasks or evaluations**
-to `KeptnAppContext` you need to execute the following steps:
-
-1. Create a `KeptnAppContext` custom resource that has the same name
-as your `KeptnApp`.
-2. Move the lists of pre/post-deployment tasks and evaluation from `KeptnApp`
-to `KeptnAppContext`.
-In other words, delete them from `KeptnApp.spec` and add them under the `KeptnAppContext.spec` field.
+You need the following steps to migrate an existing `KeptnApp` resource
+to work with the `KeptnAppContext` resource
+introduced in the `v1beta1` API version:
+
+1. Create a `KeptnAppContext` custom resource
+   that has the same name as your `KeptnApp`.
+2. Move the lists of pre/post-deployment tasks and evaluations
+   from `KeptnApp` to `KeptnAppContext`.
+   In other words, delete them from `KeptnApp.spec`
+   and add them under the `KeptnAppContext.spec` field.
 3. Add the `app.kubernetes.io/managed-by: keptn` annotation
-to `KeptnApp`.
+   to the `KeptnApp` resource if it is not already there.
 
 > **Note**
-Please make sure all of your application resources
-(such as Pods, Deployments, StatefulSets or DaemonSets)
+Be sure that all of your application resources
+(such as
+[Pods](https://kubernetes.io/docs/concepts/workloads/pods/),
+[Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
+[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/),
+and
+[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/)
 have the proper annotations/labels set.
 These annotations/labels (especially the
 `app.kubernetes.io/part-of` or `keptn.sh/app`)
@@ -53,11 +62,45 @@ Let's say we have the following `KeptnApp` in our cluster:
 {% include "./assets/keptnapp.yaml" %}
 ```
 
-Applying the migration steps from the previous subsection, we get the
-following result:
+After applying the migration steps from the previous subsection,
+you see the following changes:
+
+* The `app.kubernetes.io/managed-by` annotation
+  has been added to the `metadata.labels` section of the revised `KeptnApp` resource.
+
+     If your original `KeptnApp` resource was auto-generated,
+     it already had this annotation.
+
+* The list of tasks and evaluations
+has been moved from the `KeptnApp` resource
+to the `KeptnAppContext` resource.
 
 ```yaml
 {% include "./assets/keptnapp-migrated.yaml" %}
 ```
 
 These modified resources can be now applied to your cluster.
+
+## What's next?
+
+Making these modifications does not alter the behavior of Keptn.
+However, you might want to enhance your traces, tasks, and evaluations
+with the new functionality that is available:
+
+* Add context metadata to your traces.
+  This allows you to include information
+  like the stage into which the application is deployed, a commit ID,
+  or other information relevant to the deployment traces of
+  the application and its workloads.
+  For instructions, see
+  [Metadata](../../guides/metadata.md).
+* Add `KEPTN_CONTEXT` information to the `function` code in your
+  [KeptnTaskDefinition](../../reference/crd-reference/taskdefinition.md)
+  resource.
+  This allows you to correlate a task to a specific application/workload,
+  provide information about the phase in which the task is executed,
+  and access any metadata that has been attached to the application/workload
+  such as commit ID or user name.
+  For instructions, see
+  [Context](../../guides/tasks.md#context).
+