docs: restructure migration section (#2867)

Signed-off-by: odubajDT <ondrej.dubaj@dynatrace.com>
keptn · Jan 24, 2024 · 9f34c7d · 9f34c7d
1 parent 5c14bf5
commit 9f34c7d
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 47 deletions.
diff --git a/docs/docs/guides/slo.md b/docs/docs/guides/slo.md
@@ -35,7 +35,7 @@ For more information,see:
 
 * [SLO converter](https://github.com/keptn/lifecycle-toolkit/blob/main/metrics-operator/converter/slo_converter.md#slo-converter)
 * [SLI converter](https://github.com/keptn/lifecycle-toolkit/blob/main/metrics-operator/converter/sli_converter.md#sli-converter)
-* [Migrate Quality Gates](../migrate/metrics-observe.md)
+* [Migrate Quality Gates](../migrate/keptn/metrics-observe.md)
 
 The Analysis result is exposed as an OpenTelemetry metric
 and can be displayed on dashboard tools, such as Grafana.

diff --git a/docs/docs/migrate/index.md → docs/docs/migrate/keptn/index.md b/docs/docs/migrate/index.md → docs/docs/migrate/keptn/index.md
diff --git a/docs/docs/migrate/metrics-observe.md → docs/docs/migrate/keptn/metrics-observe.md b/docs/docs/migrate/metrics-observe.md → docs/docs/migrate/keptn/metrics-observe.md
@@ -7,32 +7,32 @@ comments: true
 The SLIs and SLOs used for Keptn v1 quality gates can be ported to
 appropriate Keptn facilities:
 
-* [Keptn Metrics](../guides/evaluatemetrics.md/)
+* [Keptn Metrics](../../guides/evaluatemetrics.md/)
   allow you to define and view metrics
   from multiple data sources in your Kubernetes cluster.
 * Use
-  [Keptn Evaluations](../guides/evaluations.md)
+  [Keptn Evaluations](../../guides/evaluations.md)
   to do a simple evaluation of the metrics data you capture.
   To implement this, transfer the information from the Keptn v1
   [sli.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/sli/)
   and
   [slo.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/slo/)
   files into
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resources.
 
 * Keptn v1 calculations that use weighting and scoring
   can be converted to use the
-  [Keptn Analysis](../guides/slo.md)
+  [Keptn Analysis](../../guides/slo.md)
   feature.
   Tools are provided to help with this conversion;
   see below.
 
 By default, Keptn includes additional observability features
 that are not included in Keptn v1:
 
-* [DORA metrics](../guides/dora.md)
-* [OpenTelemetry observability](../guides/otel.md)
+* [DORA metrics](../../guides/dora.md)
+* [OpenTelemetry observability](../../guides/otel.md)
 
 ## Paradigm changes
 
@@ -43,7 +43,7 @@ differs from that of Keptn v1 quality gates:
   using Helm charts and standard practices.
 * Keptn supports multiple instances of multiple data providers.
 * You must populate a
-  [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource
+  [KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md) resource
   for each instance of each data provider.
   This resource specifies the URL and namespace for the data provider
   and gives it a unique `name` that can be referenced
@@ -57,17 +57,17 @@ differs from that of Keptn v1 quality gates:
 ## Transfer Keptn v1 SLIs/SLOs to evaluation resources
 
 Simple comparisons of data can be implemented as
-[Keptn Evaluations](../guides/evaluations.md).
+[Keptn Evaluations](../../guides/evaluations.md).
 To implement this:
 
 * Transfer the information from the Keptn v1
   [sli.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/sli/)
   files into
-  [KeptnMetric](../reference/crd-reference/metric.md) resources
+  [KeptnMetric](../../reference/crd-reference/metric.md) resources
 * Transfer the information from the Keptn v1
   [slo.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/slo/)
   files into
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resources.
 
 ## Convert Keptn v1 SLIs/SLOs to Analysis resources
@@ -96,7 +96,7 @@ The process is:
    The following command sequence converts a Keptn v1
    [sli.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/sli/)
    file to a Keptn
-   [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md)
+   [AnalysisValueTemplate](../../reference/crd-reference/analysisvaluetemplate.md)
    resource:
 
    <!---x-release-please-start-version-->
@@ -143,7 +143,7 @@ kubectl apply -f analysis-value-template.yaml -n keptn-lifecycle-poc
    The process of converting the Keptn v1
    [slo.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/slo/)
    files to
-   [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md)
+   [AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md)
    resources is similar to the process of converting the SLIs.
    Use the following command sequence:
 
@@ -175,7 +175,7 @@ kubectl apply -f analysis-definition.yaml -n keptn-lifecycle-poc
 
 1. Create a `KeptnMetricsProvider` resource
 
-   A [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md)
+   A [KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md)
    resource configures the data provider from which the values
    for the `AnalysisValueTemplate` resource are fetched.
    This same resource is used for any metrics and evaluations you are using.
@@ -195,7 +195,7 @@ kubectl apply -f analysis-definition.yaml -n keptn-lifecycle-poc
 
    Create a yaml file (such as `analysis-instance.yaml`)
    to populate the
-   [Analysis](../reference/crd-reference/analysis.md)
+   [Analysis](../../reference/crd-reference/analysis.md)
    resource that defines the specific analysis you want to run.
    Specify the following:
 

diff --git a/docs/docs/migrate/strategy.md → docs/docs/migrate/keptn/strategy.md b/docs/docs/migrate/strategy.md → docs/docs/migrate/keptn/strategy.md
@@ -6,11 +6,11 @@ comments: true
 
 Before you begin the migration project,
 we suggest that you run through the exercises in
-[Getting started](../getting-started/index.md)
+[Getting started](../../getting-started/index.md)
 to familiarize yourself with how Keptn works.
 When you are ready to begin the migration,
 follow the instructions in
-[Installation and upgrade](../installation/index.md)
+[Installation and upgrade](../../installation/index.md)
 to set up your Kubernetes cluster
 and install Keptn on it.
 
@@ -31,7 +31,7 @@ Keptn targets deployments that run on Kubernetes
 but some Keptn functionality can be used with deployments
 that do not run on Kubernetes.
 See
-[Keptn for non-Kubernetes deployments](../use-cases/non-k8s.md)
+[Keptn for non-Kubernetes deployments](../../use-cases/non-k8s.md)
 for details.
 
 Some key points:
@@ -43,13 +43,13 @@ Some key points:
   [shipyard.yaml](https://v1.keptn.sh/docs/1.0.x/reference/files/shipyard/)
   file as Keptn v1 does.
   * See the
-    [Lifecycle CRD Reference](../reference/crd-reference/index.md)
+    [Lifecycle CRD Reference](../../reference/crd-reference/index.md)
     and
-    [Metrics CRD Reference](../reference/crd-reference/index.md)
+    [Metrics CRD Reference](../../reference/crd-reference/index.md)
     section for pages that describe the Keptn manifests
     that you populate manually for Keptn.
   * See the
-    [API Reference](../reference/api-reference/index.md)
+    [API Reference](../../reference/api-reference/index.md)
     for a comprehensive reference to all resources
     defined for Keptn.
 
@@ -62,7 +62,7 @@ Some key points:
   the user-defined requirements.
 
 * Keptn operates on a
-  [KeptnApp](../reference/crd-reference/app.md)
+  [KeptnApp](../../reference/crd-reference/app.md)
   resource
   that is an amalgamation of multiple Kubernetes workloads,
   which together comprise the released application.
@@ -94,7 +94,7 @@ Some key points:
 
 For in-depth information about Keptn components
 and how they work, see the
-[Architecture](../components/index.md)
+[Architecture](../../components/index.md)
 section.
 
 ## Disposition of Keptn v1 components in Keptn
@@ -139,10 +139,10 @@ and translate that into an appropriate resource.
 The closest analogy is a Kubernetes
 [workload](https://kubernetes.io/docs/concepts/workloads/)
 but some services may be translated into
-[KeptnTaskDefinition](../reference/crd-reference/app.md)
+[KeptnTaskDefinition](../../reference/crd-reference/app.md)
 or other resources.
  See
-[Working with Keptn tasks](../guides/tasks.md)
+[Working with Keptn tasks](../../guides/tasks.md)
 for more information.
 
 For example:
@@ -170,7 +170,7 @@ when architecting the migration:
 
 * A **deployment stage** -- may define sequences of tasks
     that should be translated into
-    [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md)
+    [KeptnTaskDefinition](../../reference/crd-reference/taskdefinition.md)
     resources that are executed pre- and post-deployment
 * A **testing stage** may define sequences of tasks
     that should be translated into `KeptnTaskDefinition` resources
@@ -199,7 +199,7 @@ In this way, you can define arbitrary sequences of any tasks
 at any length and also link (or chain) sequences together
 to form (primitive) workflows.
 When migrating, these sequences of tasks can often be translated into
-[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md)
+[KeptnTaskDefinition](../../reference/crd-reference/taskdefinition.md)
 resources that are defined to run either pre- or post-deployment
 of the pod-scheduling phase.
 
@@ -233,13 +233,13 @@ that is appropriate for the activity:
   or [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/),
   workload.
   You can code
-  [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md)
+  [KeptnTaskDefinition](../../reference/crd-reference/taskdefinition.md)
   and
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resources that are configured
   to run either pre- or post-deployment tasks
 * An **evaluation task** becomes a
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resource.
 * All other standard tasks
   (**action**, **approval**, **get-action**, **rollback**,
@@ -271,7 +271,7 @@ such as Prometheus, Dynatrace, or Datadog,
 which is configured as a Keptn integration.
 
 When migrating to Keptn, you need to define a
-[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md)
+[KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md)
 resource for the data provider(s) you are using.
 Note that Keptn allows you to support multiple data providers
 and multiple instances of each data provider for your SLIs
@@ -280,18 +280,18 @@ whereas Keptn v1 only allows you to use one SLI per project.
 The queries defined for the Keptn v1 SLIs
 should be translated into an appropriate Keptn resource:
 
-* [KeptnMetric](../reference/crd-reference/metric.md)
+* [KeptnMetric](../../reference/crd-reference/metric.md)
 resources
   to do
-  [evaluations](../guides/evaluations.md)
+  [evaluations](../../guides/evaluations.md)
   with
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resources.
-* [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md)
+* [AnalysisValueTemplate](../../reference/crd-reference/analysisvaluetemplate.md)
   resources to do
-  [analyses](../guides/slo.md)
+  [analyses](../../guides/slo.md)
   with
-  [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md)
+  [AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md)
   resources.
   Tools are provided to convert Keptn v1 SLIs and SLOs
   to Keptn resources; see
@@ -305,17 +305,17 @@ Keptn v1
 can be implemented on Keptn as evaluations or analyses:
 
 * Simple evaluations of an SLI can be implemented as
-  [Evaluations](../guides/evaluations.md)
+  [Evaluations](../../guides/evaluations.md)
   which are defined as
-  [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md)
+  [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md)
   resources.
 
 * Complex analyses that use weighting and scoring
   and analyze the value over a specified time frame
   can be implemented as
-  [Analyses](../guides/slo.md)
+  [Analyses](../../guides/slo.md)
   that are defined in
-  [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md)
+  [AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md)
   resources.
   Tools are provided to convert Keptn v1 SLIs and SLOs
   to Keptn resources; see
@@ -340,7 +340,7 @@ but it does provide limited "Day 2" facilities:
   and automatically add those resources to your configuration
   based on the `ReplicaSet` resources you have defined.
   See
-  [Using the HorizontalPodAutoscaler](../use-cases/hpa.md)
+  [Using the HorizontalPodAutoscaler](../../use-cases/hpa.md)
   for more information.
 
 ### Integrations and services in JES
@@ -350,7 +350,7 @@ Most functionality coded using the Keptn v1
 (Job Executor Service) facility
 can simply be moved into a `KeptnTaskDefinition` resource
 that uses the
-[container-runtime runner](../reference/crd-reference/taskdefinition.md/#synopsis-for-container-runtime).
+[container-runtime runner](../../reference/crd-reference/taskdefinition.md/#synopsis-for-container-runtime).
 If the JES container code is written in JavaScript or TypeScript,
 you may be able to use the `deno-runtime` runner.
 If the JES container code is written in Python 3,

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -161,10 +161,11 @@ nav:
               - KeptnMetricsProvider: docs/reference/crd-reference/metricsprovider.md
               - KeptnTask: docs/reference/crd-reference/task.md
               - KeptnTaskDefinition: docs/reference/crd-reference/taskdefinition.md
-      - Migrating to Keptn:
-          - docs/migrate/index.md
-          - Migration strategy: docs/migrate/strategy.md
-          - Migrate Quality Gates: docs/migrate/metrics-observe.md
+      - Migration:
+          - Migrating to Keptn:
+              - docs/migrate/keptn/index.md
+              - Migration strategy: docs/migrate/keptn/strategy.md
+              - Migrate Quality Gates: docs/migrate/keptn/metrics-observe.md
   - Contributing:
       - docs/contribute/index.md
       - General information: