docs: restructure content (keptn#2522)

Co-authored-by: Moritz Wiesinger <[email protected]>

.github/actions/spelling/expect.txt

@@ -225,7 +225,7 @@ hidechildren
 homedata
 homeobservability
 homeorchestrate
-horizontalpodautoscaler
+horizontalpodautoscalers
 hpa
 hreflang
 htmltest

docs/content/en/_index.md

@@ -100,7 +100,7 @@ Gain confidence in your work with pre-/post-deployment checks
 {{% readfile "partials/_index-observability-right.md" %}}
 </div>
 </div>
-<a class="btn -bg-green" href="./docs/intro/#observability">
+<a class="btn -bg-green" href="./docs/core-concepts/#observability">
     Get Started!
 </a>
 </div>
@@ -119,7 +119,7 @@ Gain confidence in your work with pre-/post-deployment checks
 {{% readfile "partials/_index-gather-metrics-right.md" %}}
 </div>
 </div>
-<a class="btn -bg-green" href="./docs/intro/#metrics">
+<a class="btn -bg-green" href="./docs/core-concepts/#metrics">
     Get Started!
 </a>
 </div>
@@ -137,7 +137,7 @@ Gain confidence in your work with pre-/post-deployment checks
 {{% readfile "partials/_index-deployment-checks-right.md" %}}
 </div>
 </div>
-<a class="btn -bg-green" href="./docs/intro/#release-lifecycle-management">
+<a class="btn -bg-green" href="./docs/core-concepts/#release-lifecycle-management">
     Get Started!
 </a>
 </div>

docs/content/en/contribute/docs/word-list/_index.md

@@ -68,7 +68,7 @@ It is important to use the related terminology correctly:
   Most of the time, we recommend just using the term "resource".
 
 * The first occurence of a CRD name in a section should be a link to the
-  [CRD YAML Reference](../../../docs/yaml-crd-ref)
+  CRD YAML Reference under the right [component](../../../docs/components)
   page if there is one.
   Otherwise, it should be a link to the appropriate spot in the
   [API Reference](../../../docs/crd-ref)

docs/content/en/contribute/software/dev-environ/_index.md

@@ -27,7 +27,7 @@ To prepare to contribute to the Keptn project, we recommend that you:
   * [klt-cert-manager](https://github.com/keptn/lifecycle-toolkit/tree/main/klt-cert-manager)
 
   Each of these is described in the
-  [Architecture](../../../docs/architecture/)
+  [Architecture](../../../docs/components/)
   section of the documentation
   and most include a *README* file with more information.
 * Study the material in
@@ -43,7 +43,7 @@ When you view the
 [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit)
 repository, you see that Keptn is composed of multiple components,
 each of which is discussed in the Architecture
-[Architecture](../../../docs/architecture/)
+[Architecture](../../../docs/components/)
 documentation:
 
 * Three Kubernetes operators
@@ -57,7 +57,7 @@ you also see the `runtimes` directory.
 This defines the runners that you can use when defining
 tasks to be run either pre- or post-deployment.
 These are discussed in
-[Runners and containers](../../../docs/implementing/tasks.md#runners-and-containers).
+[Runners and containers](../../../docs/guides/tasks.md#runners-and-containers).
 
 ## Install software
 
@@ -68,13 +68,13 @@ you need to install the following on your system:
   which allows software applications to run in isolated environments
   and makes it easier to deploy and manage them.
 * A Kubernetes cluster running an appropriate version of Kubernetes.
-  See [Supported Kubernetes versions](../../../docs/install/reqs.md/#supported-kubernetes-versions)
+  See [Supported Kubernetes versions](../../../docs/installation/_index.md#supported-kubernetes-versions)
   for details.
   Most contributors create a local
   Kubernetes-in-Docker(KinD) cluster.
   This is adequate for developing software for Keptn.
   See
-  [Kubernetes cluster](../../../docs/install/k8s.md/#create-local-kubernetes-cluster)
+  [Kubernetes cluster](../../../docs/installation/k8s.md/#create-local-kubernetes-cluster)
   for instructions.
 * [**kubectl**](https://kubernetes.io/docs/tasks/tools/):
   a command-line interface tool used for deploying

docs/content/en/docs/architecture/components/_index.md → docs/content/en/docs/components/_index.md

@@ -1,16 +1,15 @@
 ---
-title: Keptn Components
-linktitle: Components
-description: Basic understanding of Keptn Components
-weight: 20
+title: Components
+description: Understand the details of how Keptn works
+weight: 50
 ---
 
 ### Keptn Components
 
 Keptn consists of two main components:
 
 * Keptn Lifecycle Operator, which splits into two separate operators
-in Release 0.7.0 and later:
+  in Release 0.7.0 and later:
   * Lifecycle-Operator
   * Metrics-Operator
 * Keptn Lifecycle Scheduler

docs/content/en/docs/architecture/cert-manager.md → docs/content/en/docs/components/certificate-operator/_index.md

@@ -11,7 +11,7 @@ hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.htm
 The Keptn Cert Manager automatically configures TLS certificates to
 [secure communication with the Kubernetes API](https://kubernetes.io/docs/concepts/security/controlling-access/#transport-security).
 You can instead
-[use cert-manager.io](../operate/cert-manager.md)
+[use cert-manager.io](../../installation/configuration/cert-manager.md)
 for this purpose.
 
 Keptn includes a Mutating Webhook
@@ -38,7 +38,7 @@ It is included to simplify installation for new users
 and because it is much smaller than most standard certificate managers.
 However, Keptn is compatible with most certificate managers
 and can be configured to use another certificate manager if you prefer.
-See [Use Keptn with cert-manager.io](../operate/cert-manager.md)
+See [Use Keptn with cert-manager.io](../../installation/configuration/cert-manager.md)
 for instructions.
 
 ## Invalid certificate errors

docs/content/en/docs/architecture/deployment-flow.md → docs/content/en/docs/components/lifecycle-operator/deployment-flow.md

@@ -2,7 +2,7 @@
 title: Flow of deployment
 linktitle: Flow of deployment
 description: Understand the execution flow of a deployment
-weight: 35
+weight: 100
 ---
 
 Keptn deploys a
@@ -22,7 +22,7 @@ Within each phase, all tasks and evaluations for each phase
 are executed in parallel.
 They are not affected by the order
 in which evaluations and tasks are listed in the
-[KeptnApp](../yaml-crd-ref/app.md/)
+[KeptnApp](../../reference/crd-reference/app.md)
 resource
 or in the order of the pre/post-tasks and pre/post-evaluations
 that are listed in the Workflow manifests.

docs/content/en/docs/architecture/keptn-apps.md → docs/content/en/docs/components/lifecycle-operator/keptn-apps.md

@@ -2,13 +2,13 @@
 title: KeptnApp and KeptnWorkload resources
 linktitle: Keptn Applications and Keptn Workloads
 description: How Keptn applications work
-weight: 50
+weight: 110
 ---
 
 ## Keptn Workloads
 
 A
-[KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload)
+[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/_index.md#keptnworkload)
 resource augments a Kubernetes
 [Workload](https://kubernetes.io/docs/concepts/workloads/)
 with the ability to handle extra phases.
@@ -31,7 +31,7 @@ as soon as the workload manifest is applied.
 
 ## Keptn Applications
 
-A [KeptnApp](../yaml-crd-ref/app.md)
+A [KeptnApp](../../reference/crd-reference/app.md)
 resource combines multiple Kubernetes
 [workloads](https://kubernetes.io/docs/concepts/workloads/)
 into a single entity
@@ -64,12 +64,12 @@ plus specific tasks and evaluations that you define
 for the `KeptnApp` resource itself:
 
 * The annotations described in
-  [Basic annotations](../implementing/integrate.md#basic-annotations)
+  [Basic annotations](../../guides/integrate.md#basic-annotations)
   are used to automatically generate `KeptnApp` resources
   that contain the identifications required
   to run the Keptn observability features.
 * You must manually add the annotations described in
-  [Pre- and post-deployment checks](../implementing/integrate.md#pre--and-post-deployment-checks)
+  [Pre- and post-deployment checks](../../guides/integrate.md#pre--and-post-deployment-checks)
   to the basic `KeptnApp` manifest to define
   the evaluations and tasks you want to run pre- and post-deployment.
 
@@ -86,12 +86,12 @@ The timeout is provided because it may take some time
 to apply all `KeptnWorkload` resources to the cluster.
 This interval can be modified for the cluster by changing the value
 of the `keptnAppCreationRequestTimeoutSeconds` field in the
-[KeptnConfig](../yaml-crd-ref/config.md)
+[KeptnConfig](../../reference/crd-reference/config.md)
 resource.
 
 ## How basic annotations are implemented
 
-The [Basic annotations](../implementing/integrate.md#basic-annotations)
+The [Basic annotations](../../guides/integrate.md#basic-annotations)
 page gives instructions for applying the annotations or labels
 that identify the pods that Keptn should manage.
 
@@ -108,7 +108,7 @@ In other words:
   again first in the annotations, then in the labels.
 
 Keptn automatically generates appropriate
-[KeptnApp](../yaml-crd-ref/app.md)
+[KeptnApp](../../reference/crd-reference/app.md)
 resources that are used for observability,
 based on whether the `keptn.sh/app` or `app.kubernetes.io/part-of`
 annotation/label is populated:

docs/content/en/docs/architecture/components/metrics-operator.md → docs/content/en/docs/components/metrics-operator/_index.md

@@ -27,7 +27,7 @@ so they are compatible with the Kubernetes
 (HPA), which enables the horizontal scaling of workloads
 based on metrics collected from multiple observability platforms.
 See
-[Using the HorizontalPodAutoscaler](../../implementing/evaluatemetrics.md#using-the-horizontalpodautoscaler)
+[Using the HorizontalPodAutoscaler](../../use-cases/hpa.md)
 for instructions.
 
 The Metrics Operator consists of the following components:
@@ -54,18 +54,18 @@ which can be used to gain insight into the behavior and performance
 of applications running on a Kubernetes cluster.
 
 The **Metrics controller** fetches metrics from an SLI provider.
-The controller reconciles a [`KeptnMetric`](../../yaml-crd-ref/metric.md)
+The controller reconciles a [`KeptnMetric`](../../reference/crd-reference/metric.md)
 resource and updates its status with the metric value
 provided by the selected metric provider.
 Each `KeptnMetric` is identified by `name`
 and is associated with an instance of an observability platform
 that is defined in a
-[KeptnMetricsProvider](../../yaml-crd-ref/metricsprovider.md)
+[KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md)
 resource.
 
 The steps in which the controller fetches metrics are given below:
 
-1. When a [`KeptnMetric`](../../yaml-crd-ref/metric.md)
+1. When a [`KeptnMetric`](../../reference/crd-reference/metric.md)
    resource is found or modified,
    the controller checks whether the metric has been updated
    within the interval that is defined in the `spec.fetchintervalseconds` field.

docs/content/en/docs/architecture/components/scheduler.md → docs/content/en/docs/components/scheduling/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Keptn integration with Scheduling
 linktitle: Scheduler and Scheduling Gates
-description: Basic understanding of how Keptn integrates with Kubernetes Pod Scheduling
+description: Scheduler and Scheduling Gates
 weight: 80
 ---
 
@@ -31,7 +31,7 @@ to gate Pods until the required deployment checks pass.
 When a workload is applied to a Kubernetes cluster,
 the Mutating Webhook checks each Pod for annotations.
 If
-[Keptn specific annotations](../../implementing/integrate.md#basic-annotations)
+[Keptn specific annotations](../../guides/integrate.md#basic-annotations)
 are present,
 the Webhook adds a scheduling gate to the Pod called `keptn-prechecks-gate`.
 This spec tells the Kubernetes scheduling framework
@@ -72,7 +72,7 @@ a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/schedu
 ### How does the Keptn Scheduler works
 
 Firstly the Mutating Webhook checks for annotations on Pods to see if it is annotated with
-[Keptn specific annotations](../../implementing/integrate.md#basic-annotations).
+[Keptn specific annotations](../../guides/integrate.md#basic-annotations).
 If the annotations are present, the Webhook assigns the **Keptn Scheduler** to the Pod.
 This ensures that the Keptn Scheduler only gets Pods that have been annotated for it.
 A Pod `test-pod` modified by the Mutating Webhook looks as follows:

docs/content/en/docs/intro/_index.md → docs/content/en/docs/core-concepts/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Introduction to Keptn
+title: Core Concepts
 description: An introduction to Keptn and the usecases.
 weight: 10
 ---
@@ -48,7 +48,7 @@ simplifying configuration and integration into a single set of metrics.
 To learn more, see:
 
 * [Getting started with Keptn metrics](../getting-started/metrics.md)
-* [Keptn Metrics](../implementing/evaluatemetrics.md) User Guide
+* [Keptn Metrics](../guides/evaluatemetrics.md) User Guide
 
 ## Observability
 
@@ -65,7 +65,7 @@ deployment durations and failures across multiple deployment strategies.
   using different deployment strategies.
 
 * Captures
-  [DORA metrics](../implementing/dora.md)
+  [DORA metrics](../guides/dora.md)
   and exposes them as OpenTelemetry metrics out of the box.
 
 * Reports traces and custom Keptn metrics from configured data providers
@@ -88,8 +88,8 @@ To learn more, see:
 
 * [Getting started with Keptn Observability](../getting-started/observability.md)
 * [Standardize observability](usecase-observability.md/)
-* [DORA metrics](../implementing/dora.md) User Guide
-* [OpenTelemetry observability](../implementing/otel.md) User Guide
+* [DORA metrics](../guides/dora.md) User Guide
+* [OpenTelemetry observability](../guides/otel.md) User Guide
 
 ## Release lifecycle management
 
@@ -130,12 +130,12 @@ run in sequential order.
 Keptn tasks and evaluations can be run
 for either a Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/) (single service) resource
 or a
-[KeptnApp](../yaml-crd-ref/app.md) resource,
+[KeptnApp](../reference/crd-reference/app.md) resource,
 which is a single, cohesive unit that groups multiple [workloads](https://kubernetes.io/docs/concepts/workloads/).
 For more information, see:
 
 * [Getting started with release lifecycle management](../getting-started/lifecycle-management.md)
-* [Deployment tasks](../implementing/tasks.md) User Guide
-* [Evaluations](../implementing/evaluations.md) User Guide
+* [Deployment tasks](../guides/tasks.md) User Guide
+* [Evaluations](../guides/evaluations.md) User Guide
 * [Manage release lifecycle](usecase-orchestrate.md)
-* [KeptnApp and KeptnWorkload resources](../architecture/keptn-apps.md)
+* [KeptnApp and KeptnWorkload resources](../components/lifecycle-operator/keptn-apps.md)

docs/content/en/docs/intro/usecase-observability.md → docs/content/en/docs/core-concepts/usecase-observability.md

@@ -66,15 +66,15 @@ or on a local cluster you are creating for this exercise,
 you need to do the following:
 
 1. Follow the instructions in
-   [Install and update](../install)
+   [Install and update](../installation)
    to install and enable Keptn on your cluster.
 1. Follow the instructions in
-   [Basic annotations](../implementing/integrate.md#basic-annotations)
+   [Basic annotations](../guides/integrate.md#basic-annotations)
    to integrate Keptn into your Kubernetes cluster
    by applying basic annotations
    to your [workload](https://kubernetes.io/docs/concepts/workloads/) resources.
    and to create appropriate
-   [KeptnApp](../yaml-crd-ref/app.md)
+   [KeptnApp](../reference/crd-reference/app.md)
    resources that aggregate
    all the [workloads](https://kubernetes.io/docs/concepts/workloads/) for a logical deployment into a single resource.
 
@@ -86,7 +86,7 @@ about your deployments.
 Keptn starts collecting these metrics
 as soon as you annotate the `Deployment` resource.
 See
-[DORA metrics](../implementing/dora.md)
+[DORA metrics](../guides/dora.md)
 for more details.
 
 ## Using OpenTelemetry
@@ -103,9 +103,9 @@ which allows you to trace everything done in the context of that deployment.
   [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
   for more information.
 - Follow the instructions in
-  [OpenTelemetry observability](../implementing/otel.md)
+  [OpenTelemetry observability](../guides/otel.md)
   to configure where your OpenTelemetry data is sent.
-  This requires you to define a [KeptnConfig](../yaml-crd-ref/config.md) resource
+  This requires you to define a [KeptnConfig](../reference/crd-reference/config.md) resource
   that defines the URL and port of the OpenTelemetry collector.
   For our example, this is in the
   [keptnconfig.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/setup/keptn/keptnconfig.yaml)