docs: introduce KeptnApp to KeptnAppContext migration guide (#2851)

Signed-off-by: odubajDT <ondrej.dubaj@dynatrace.com>
Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
Co-authored-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>

docs/docs/installation/upgrade.md

@@ -24,6 +24,14 @@ If you installed your Keptn instance from the Manifest,
 additional steps are required to use the Helm Chart to upgrade.
 Contact us on Slack for assistance.
 
+## Upgrade to v1beta1 version
+
+If you have previously used Keptn Lifecycle Operator with API
+resources of version `v1alpha3` and `v1alpha4`, you need to
+edit manually created or edited `KeptnApp` resources.
+For further information please refer to the
+[migration section](../migrate/keptnapp/index.md).
+
 ## Upgrade to Helm from a manifest installation
 
 > **Warning**

docs/docs/migrate/keptnapp/assets/keptnapp-migrated.yaml

@@ -0,0 +1,29 @@
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnApp
+metadata:
+  name: "some-keptn-app"
+  namespace: "my-app-ns"
+  labels:
+    my-custom-label: customValue
+    app.kubernetes.io/managed-by: keptn # added annotation
+spec:
+  version: "1.2.3"
+  workloads:
+    - name: podtato-head-left-arm
+      version: 0.2.7
+  # removed pre/post-deployment tasks and evaluations
+---
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: "some-keptn-app" # created a resource with the same name as KeptnApp
+  namespace: "my-app-ns"
+spec:
+  preDeploymentTasks:    # moved pre/post-deployment tasks and evaluations
+    - pre-deployment-task
+  preDeploymentEvaluations:
+    - pre-deployment-evaluation
+  postDeploymentTasks:
+    - post-deployment-task
+  postDeploymentEvaluations:
+    - post-deployment-evaluation

docs/docs/migrate/keptnapp/assets/keptnapp.yaml

@@ -0,0 +1,20 @@
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnApp
+metadata:
+  name: "some-keptn-app"
+  namespace: "my-app-ns"
+  labels:
+    my-custom-label: customValue
+spec:
+  version: "1.2.3"
+  workloads:
+    - name: podtato-head-left-arm
+      version: 0.2.7
+  preDeploymentTasks:
+    - pre-deployment-task
+  preDeploymentEvaluations:
+    - pre-deployment-evaluation
+  postDeploymentTasks:
+    - post-deployment-task
+  postDeploymentEvaluations:
+    - post-deployment-evaluation

docs/docs/migrate/keptnapp/index.md

@@ -0,0 +1,63 @@
+# Migrating KeptnApp to KeptnAppContext
+
+The introduction of the `KeptnAppContext` resource
+in Keptn v0.11.0
+requires modifications to existing
+[KeptnApp](../../reference/crd-reference/app.md)
+resources that were generated manually.
+This page gives instructions for doing that.
+
+## 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.
+3. Add the `app.kubernetes.io/managed-by: keptn` annotation
+to `KeptnApp`.
+
+> **Note**
+Please make sure all of your application resources
+(such as Pods, Deployments, StatefulSets or DaemonSets)
+have the proper annotations/labels set.
+These annotations/labels (especially the
+`app.kubernetes.io/part-of` or `keptn.sh/app`)
+are necessary for the migration to the
+automatic app-discovery feature.
+More information about how to set up these annotations/labels
+can be found [here](../../guides/integrate.md#basic-annotations).
+
+## Example of migration
+
+Here, we provide an example of how to
+migrate the `KeptnApp` definition to the `KeptnAppContext`.
+Let's say we have the following `KeptnApp` in our cluster:
+
+```yaml
+{% include "./assets/keptnapp.yaml" %}
+```
+
+Applying the migration steps from the previous subsection, we get the
+following result:
+
+```yaml
+{% include "./assets/keptnapp-migrated.yaml" %}
+```
+
+These modified resources can be now applied to your cluster.

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

@@ -166,6 +166,10 @@ 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.
+For more information please refer
+to the [migration section](../../migrate/keptnapp/index.md).
 
 ## See also
 

mkdocs.yml

@@ -171,6 +171,8 @@ nav:
               - docs/migrate/keptn/index.md
               - Migration strategy: docs/migrate/keptn/strategy.md
               - Migrate Quality Gates: docs/migrate/keptn/metrics-observe.md
+          - KeptnApp Migration:
+              - docs/migrate/keptnapp/index.md
   - Contributing:
       - docs/contribute/index.md
       - General information: