From 9f34c7d0d33e8dc904b20ac4e46b6ae795d213bc Mon Sep 17 00:00:00 2001 From: odubajDT <93584209+odubajDT@users.noreply.github.com> Date: Wed, 24 Jan 2024 08:57:32 +0100 Subject: [PATCH] docs: restructure migration section (#2867) Signed-off-by: odubajDT --- docs/docs/guides/slo.md | 2 +- docs/docs/migrate/{ => keptn}/index.md | 0 .../migrate/{ => keptn}/metrics-observe.md | 28 +++++----- docs/docs/migrate/{ => keptn}/strategy.md | 56 +++++++++---------- mkdocs.yml | 9 +-- 5 files changed, 48 insertions(+), 47 deletions(-) rename docs/docs/migrate/{ => keptn}/index.md (100%) rename docs/docs/migrate/{ => keptn}/metrics-observe.md (92%) rename docs/docs/migrate/{ => keptn}/strategy.md (87%) diff --git a/docs/docs/guides/slo.md b/docs/docs/guides/slo.md index b520604389..1b45ed1ced 100644 --- 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 b/docs/docs/migrate/keptn/index.md similarity index 100% rename from docs/docs/migrate/index.md rename to docs/docs/migrate/keptn/index.md diff --git a/docs/docs/migrate/metrics-observe.md b/docs/docs/migrate/keptn/metrics-observe.md similarity index 92% rename from docs/docs/migrate/metrics-observe.md rename to docs/docs/migrate/keptn/metrics-observe.md index 54f4f9c002..f7dc395c82 100644 --- a/docs/docs/migrate/metrics-observe.md +++ b/docs/docs/migrate/keptn/metrics-observe.md @@ -7,23 +7,23 @@ 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. @@ -31,8 +31,8 @@ appropriate Keptn facilities: 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: @@ -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 b/docs/docs/migrate/keptn/strategy.md similarity index 87% rename from docs/docs/migrate/strategy.md rename to docs/docs/migrate/keptn/strategy.md index d01c353c00..fa93afac13 100644 --- a/docs/docs/migrate/strategy.md +++ b/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 index 72de4a74d2..1ce63b50b3 100644 --- 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: