diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index 2337936cfa..32bbf7fb6a 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -225,7 +225,7 @@ hidechildren homedata homeobservability homeorchestrate -horizontalpodautoscaler +horizontalpodautoscalers hpa hreflang htmltest diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md index 520a4cafe4..8ee4ef46fa 100644 --- a/docs/content/en/_index.md +++ b/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" %}} - + Get Started! @@ -119,7 +119,7 @@ Gain confidence in your work with pre-/post-deployment checks {{% readfile "partials/_index-gather-metrics-right.md" %}} - + Get Started! @@ -137,7 +137,7 @@ Gain confidence in your work with pre-/post-deployment checks {{% readfile "partials/_index-deployment-checks-right.md" %}} - + Get Started! diff --git a/docs/content/en/contribute/docs/word-list/_index.md b/docs/content/en/contribute/docs/word-list/_index.md index 40f24895eb..90eaa0ae99 100644 --- a/docs/content/en/contribute/docs/word-list/_index.md +++ b/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) diff --git a/docs/content/en/contribute/software/dev-environ/_index.md b/docs/content/en/contribute/software/dev-environ/_index.md index 430d20ec17..830adadde6 100644 --- a/docs/content/en/contribute/software/dev-environ/_index.md +++ b/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 diff --git a/docs/content/en/docs/architecture/_index.md b/docs/content/en/docs/architecture/_index.md deleted file mode 100644 index 32481d5266..0000000000 --- a/docs/content/en/docs/architecture/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Architecture -linktitle: Architecture -description: Understand the details of how Keptn works -weight: 50 ---- - -### Keptn Components diff --git a/docs/content/en/docs/architecture/components/_index.md b/docs/content/en/docs/components/_index.md similarity index 84% rename from docs/content/en/docs/architecture/components/_index.md rename to docs/content/en/docs/components/_index.md index 8975060d0c..23ef55a6c4 100644 --- a/docs/content/en/docs/architecture/components/_index.md +++ b/docs/content/en/docs/components/_index.md @@ -1,8 +1,7 @@ --- -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 @@ -10,7 +9,7 @@ weight: 20 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 diff --git a/docs/content/en/docs/architecture/cert-manager.md b/docs/content/en/docs/components/certificate-operator/_index.md similarity index 93% rename from docs/content/en/docs/architecture/cert-manager.md rename to docs/content/en/docs/components/certificate-operator/_index.md index d557e5df59..edac8a8105 100644 --- a/docs/content/en/docs/architecture/cert-manager.md +++ b/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 diff --git a/docs/content/en/docs/architecture/components/lifecycle-operator.md b/docs/content/en/docs/components/lifecycle-operator/_index.md similarity index 100% rename from docs/content/en/docs/architecture/components/lifecycle-operator.md rename to docs/content/en/docs/components/lifecycle-operator/_index.md diff --git a/docs/content/en/docs/architecture/deployment-flow.md b/docs/content/en/docs/components/lifecycle-operator/deployment-flow.md similarity index 98% rename from docs/content/en/docs/architecture/deployment-flow.md rename to docs/content/en/docs/components/lifecycle-operator/deployment-flow.md index 8968aa1bae..4b52aac84a 100644 --- a/docs/content/en/docs/architecture/deployment-flow.md +++ b/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. diff --git a/docs/content/en/docs/architecture/keptn-apps.md b/docs/content/en/docs/components/lifecycle-operator/keptn-apps.md similarity index 91% rename from docs/content/en/docs/architecture/keptn-apps.md rename to docs/content/en/docs/components/lifecycle-operator/keptn-apps.md index 8a4ae11823..419c8334dd 100644 --- a/docs/content/en/docs/architecture/keptn-apps.md +++ b/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: diff --git a/docs/content/en/docs/architecture/components/metrics-operator.md b/docs/content/en/docs/components/metrics-operator/_index.md similarity index 92% rename from docs/content/en/docs/architecture/components/metrics-operator.md rename to docs/content/en/docs/components/metrics-operator/_index.md index 5e82de1eb9..74442b3986 100644 --- a/docs/content/en/docs/architecture/components/metrics-operator.md +++ b/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. diff --git a/docs/content/en/docs/architecture/components/scheduler.md b/docs/content/en/docs/components/scheduling/_index.md similarity index 96% rename from docs/content/en/docs/architecture/components/scheduler.md rename to docs/content/en/docs/components/scheduling/_index.md index c7ffe424b1..f83e449084 100644 --- a/docs/content/en/docs/architecture/components/scheduler.md +++ b/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: diff --git a/docs/content/en/docs/intro/_index.md b/docs/content/en/docs/core-concepts/_index.md similarity index 91% rename from docs/content/en/docs/intro/_index.md rename to docs/content/en/docs/core-concepts/_index.md index fa1f240a91..f4867b43e1 100644 --- a/docs/content/en/docs/intro/_index.md +++ b/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) diff --git a/docs/content/en/docs/implementing/assets/dynatrace_dora_dashboard.png b/docs/content/en/docs/core-concepts/assets/dynatrace_dora_dashboard.png similarity index 100% rename from docs/content/en/docs/implementing/assets/dynatrace_dora_dashboard.png rename to docs/content/en/docs/core-concepts/assets/dynatrace_dora_dashboard.png diff --git a/docs/content/en/docs/intro/usecase-observability.md b/docs/content/en/docs/core-concepts/usecase-observability.md similarity index 94% rename from docs/content/en/docs/intro/usecase-observability.md rename to docs/content/en/docs/core-concepts/usecase-observability.md index 7e30f768ff..0e88d53b7d 100644 --- a/docs/content/en/docs/intro/usecase-observability.md +++ b/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) diff --git a/docs/content/en/docs/intro/usecase-orchestrate.md b/docs/content/en/docs/core-concepts/usecase-orchestrate.md similarity index 93% rename from docs/content/en/docs/intro/usecase-orchestrate.md rename to docs/content/en/docs/core-concepts/usecase-orchestrate.md index 1dbb44d12f..aa7eef70cf 100644 --- a/docs/content/en/docs/intro/usecase-orchestrate.md +++ b/docs/content/en/docs/core-concepts/usecase-orchestrate.md @@ -75,14 +75,14 @@ and did not previously set up your cluster for the you need to do the following: 1. Follow the instructions in - [Install and update](../install/_index.md) + [Install and update](../installation/_index.md) to install and enable Keptn on your cluster. 1. Follow the instructions in - [Annotate workload](../implementing/integrate.md#basic-annotations) + [Annotate workload](../guides/integrate.md#basic-annotations) to integrate Keptn into your Kubernetes cluster by applying basic annotations to your `Deployment` resource. This also creates appropriate - [KeptnApp](../yaml-crd-ref/app.md) resources + [KeptnApp](../reference/crd-reference/app.md) resources which aggregate [workloads](https://kubernetes.io/docs/concepts/workloads/) that are combined into the released product, regardless of the tools being used. @@ -90,7 +90,7 @@ you need to do the following: An `evaluation` is a KeptnMetric that has a defined target value. Evaluations are resources that are defined in a -[KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) yaml file. In our example, evaluations are defined in the [keptn-evaluations.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-evaluations.yaml) @@ -122,7 +122,7 @@ You could include objectives and additional metrics in this evaluation. ## Define tasks to be performed pre- and post-deployment Tasks are resources that are defined in a -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) file. In our example, the tasks are defined in the [keptn-tasks.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-tasks.yaml) @@ -160,7 +160,7 @@ you can also use Python 3 to define your task, or you can define a standard Kubernetes container that uses the image, runner, and runtime dependencies that you choose. For more information, see -[Working with Keptn tasks](../implementing/tasks.md). +[Working with Keptn tasks](../guides/tasks.md). You can view the actual JavaScript code for the task in the repository. You see that "context" is important in this code. @@ -173,7 +173,7 @@ is protected by a secret, the task definition also specifies that secret. ## Integrate evaluations and tasks into the cluster Follow the instructions in -[Annotate workload](../implementing/integrate.md#pre--and-post-deployment-checks) +[Annotate workload](../guides/integrate.md#pre--and-post-deployment-checks) to integrate the evaluations and tasks you defined into the cluster by applying annotations to the `Deployment` resource. diff --git a/docs/content/en/docs/crd-ref/_index.md b/docs/content/en/docs/crd-ref/_index.md index f9c7262800..38875a2479 100644 --- a/docs/content/en/docs/crd-ref/_index.md +++ b/docs/content/en/docs/crd-ref/_index.md @@ -19,7 +19,9 @@ Keptn APIs follow API versioning conventions recommended by Kubernetes. Keptn generates most of the resources it needs without requiring manual input. -[Manifest CRD Reference](../yaml-crd-ref) +[Lifecycle CRD Reference](../reference/crd-reference) +and +[Metrics CRD Reference](../reference/crd-reference) contains reference pages for the manifests that must be populated manually. diff --git a/docs/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md index a38869cd75..c749d36d4d 100644 --- a/docs/content/en/docs/getting-started/_index.md +++ b/docs/content/en/docs/getting-started/_index.md @@ -1,5 +1,5 @@ --- -title: Getting started +title: Get started description: Get started with Keptn weight: 20 --- diff --git a/docs/content/en/docs/getting-started/lifecycle-management.md b/docs/content/en/docs/getting-started/lifecycle-management.md index a338912236..9a3ed83aed 100644 --- a/docs/content/en/docs/getting-started/lifecycle-management.md +++ b/docs/content/en/docs/getting-started/lifecycle-management.md @@ -23,7 +23,7 @@ When Keptn is successfully monitoring your deployments, it can also run arbitrar - post-deployment (after the post is scheduled) > Pre and post deployments can also run on a KeptnApp level. -> See [annotations to KeptnApp](../implementing/integrate.md#annotations-to-keptnapp) +> See [annotations to KeptnApp](../guides/integrate.md#annotations-to-keptnapp) ## Prerequisites: Deploy webhook sink @@ -140,7 +140,7 @@ The webhook sync should show this: ![webhook sync](../assets/webhook.site.3.png) -Incidentally, this is exactly how you can use Keptn with [applications deployed outside of Kubernetes](../implementing/tasks-non-k8s-apps.md). +Incidentally, this is exactly how you can use Keptn with [applications deployed outside of Kubernetes](../use-cases/non-k8s.md). > Note: If you want to trigger this multiple times, you must change the KeptnTask name. > @@ -219,7 +219,7 @@ Do this by using the `keptn.sh/pre-deployment-tasks` label. ## Further Information There is a lot more you can do with KeptnTasks. -See [pre and post deployment checks page](../implementing/integrate.md#pre--and-post-deployment-checks) to find out more. +See [pre and post deployment checks page](../guides/integrate.md#pre--and-post-deployment-checks) to find out more. ## What's next? diff --git a/docs/content/en/docs/getting-started/metrics.md b/docs/content/en/docs/getting-started/metrics.md index 6ba4779caf..15512b46bb 100644 --- a/docs/content/en/docs/getting-started/metrics.md +++ b/docs/content/en/docs/getting-started/metrics.md @@ -1,5 +1,5 @@ --- -title: Keptn metrics +title: Keptn Metrics description: Enhance your deployment with custom Keptn metrics weight: 30 --- @@ -48,11 +48,11 @@ series. After completing this exercise, you may want to do the other exercises: -- In [Standardize observability](../intro/usecase-observability.md), +- In [Standardize observability](../core-concepts/usecase-observability.md), you learn how to standardize access to the observability data for your cluster. - In - [Manage release lifecycle](../intro/usecase-orchestrate.md), + [Manage release lifecycle](../core-concepts/usecase-orchestrate.md), you learn how to implement pre- and post-deployment tasks and evaluations to orchestrate the flow of all the [workloads](https://kubernetes.io/docs/concepts/workloads/) @@ -60,14 +60,14 @@ you may want to do the other exercises: The steps to implement metrics in an existing cluster are: -1. [Install Keptn](../install/install.md) +1. [Install Keptn](../installation/_index.md) 1. Configure the metrics you want to use: - [Define metrics providers](#define-metrics-providers) - [Define KeptnMetric information](#define-keptnmetric-information) - [View available metrics](#view-available-metrics) If you want to create your own cluster to run this exercise, -follow the instructions in [Installation](../install/install.md). +follow the instructions in [Installation](../installation/_index.md). ## Define metrics to use @@ -82,7 +82,7 @@ as well as the Kubernetes CLI. ### Define metrics providers Populate a -[KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource for each external observability platform you want to use. For our example, we define two observability platforms: @@ -139,7 +139,7 @@ spec: ### Define KeptnMetric information -The [KeptnMetric](../yaml-crd-ref/metric.md) resource +The [KeptnMetric](../reference/crd-reference/metric.md) resource defines the information you want to gather, specified as a query for the particular observability platform you are using. @@ -278,7 +278,7 @@ The Kubernetes HorizontalPodAutoscaler (HPA) uses metrics to provide autoscaling for the cluster. HPA can retrieve KeptnMetrics and use those metrics to implement HPA. See -Using the [HorizontalPodAutoscaler](../implementing/evaluatemetrics.md/#using-the-horizontalpodautoscaler) +Using the [HorizontalPodAutoscaler](../use-cases/hpa.md) for detailed information. ## Learn more @@ -286,6 +286,6 @@ for detailed information. To learn more about the Keptn Metrics Server, see: - Architecture: - [Keptn Metrics Operator](../architecture/components/metrics-operator.md) + [Keptn Metrics Operator](../components/metrics-operator/_index.md) - More information about implementing Keptn Metrics: - [Keptn Metrics](../implementing/evaluatemetrics.md) + [Keptn Metrics](../guides/evaluatemetrics.md) diff --git a/docs/content/en/docs/getting-started/observability.md b/docs/content/en/docs/getting-started/observability.md index d11c78997f..51ebd50a37 100644 --- a/docs/content/en/docs/getting-started/observability.md +++ b/docs/content/en/docs/getting-started/observability.md @@ -525,7 +525,7 @@ spec: that failed to deploy, perhaps because a `preDeploymentEvaluation` or `preDeploymentTask` failed. See - [Restart an Application Deployment](../implementing/restart-application-deployment.md) + [Restart an Application Deployment](../guides/restart-application-deployment.md) for a longer discussion of this. - **workloads** - **name** - name of this Kubernetes @@ -545,23 +545,23 @@ If used, these fields must be populated manually: - **preDeploymentTasks** -- list each task to be run as part of the pre-deployment stage. Task names must match the value of the `metadata.name` field - for the associated [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) resource. + for the associated [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resource. - **postDeploymentTasks** -- list each task to be run as part of the post-deployment stage. Task names must match the value of the `metadata.name` field for the associated - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resource. - **preDeploymentEvaluations** -- list each evaluation to be run as part of the pre-deployment stage. Evaluation names must match the value of the `metadata.name` field for the associated - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resource. - **postDeploymentEvaluations** -- list each evaluation to be run as part of the post-deployment stage. Evaluation names must match the value of the `metadata.name` field - for the associated [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + for the associated [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resource. ## Example @@ -589,10 +589,10 @@ You may have noticed that the `KeptnApp` Custom Resources are created automatica However, you can override this automatic behaviour by creating a custom `KeptnApp` CRD. In this way, you are in full control of what constitutes a Keptn Application. -See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information. +See [KeptnApp Reference page](../reference/crd-reference/app.md) for more information. ## What's next? Keptn can run pre and post deployment tasks and SLO evaluations automatically. -Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks.md). +Continue the Keptn learning journey by [adding deployment tasks](../guides/tasks.md). diff --git a/docs/content/en/docs/implementing/_index.md b/docs/content/en/docs/guides/_index.md similarity index 86% rename from docs/content/en/docs/implementing/_index.md rename to docs/content/en/docs/guides/_index.md index 0a0c76e628..c265f0ed32 100644 --- a/docs/content/en/docs/implementing/_index.md +++ b/docs/content/en/docs/guides/_index.md @@ -1,5 +1,5 @@ --- -title: User Guides +title: Guides description: Learn how to implement metrics, observability, and release lifecycle management with Keptn weight: 40 --- diff --git a/docs/content/en/docs/implementing/assets/app-updated-version.yaml b/docs/content/en/docs/guides/assets/app-updated-version.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/app-updated-version.yaml rename to docs/content/en/docs/guides/assets/app-updated-version.yaml diff --git a/docs/content/en/docs/implementing/assets/app-with-new-workload.yaml b/docs/content/en/docs/guides/assets/app-with-new-workload.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/app-with-new-workload.yaml rename to docs/content/en/docs/guides/assets/app-with-new-workload.yaml diff --git a/docs/content/en/docs/implementing/assets/deployment-initial.yaml b/docs/content/en/docs/guides/assets/deployment-initial.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/deployment-initial.yaml rename to docs/content/en/docs/guides/assets/deployment-initial.yaml diff --git a/docs/content/en/docs/implementing/assets/deployment-new-image-and-version.yaml b/docs/content/en/docs/guides/assets/deployment-new-image-and-version.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/deployment-new-image-and-version.yaml rename to docs/content/en/docs/guides/assets/deployment-new-image-and-version.yaml diff --git a/docs/content/en/docs/implementing/assets/deployment-new-image.yaml b/docs/content/en/docs/guides/assets/deployment-new-image.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/deployment-new-image.yaml rename to docs/content/en/docs/guides/assets/deployment-new-image.yaml diff --git a/docs/content/en/docs/intro/assets/dynatrace_dora_dashboard.png b/docs/content/en/docs/guides/assets/dynatrace_dora_dashboard.png similarity index 100% rename from docs/content/en/docs/intro/assets/dynatrace_dora_dashboard.png rename to docs/content/en/docs/guides/assets/dynatrace_dora_dashboard.png diff --git a/docs/content/en/docs/implementing/assets/new-deployment.yaml b/docs/content/en/docs/guides/assets/new-deployment.yaml similarity index 100% rename from docs/content/en/docs/implementing/assets/new-deployment.yaml rename to docs/content/en/docs/guides/assets/new-deployment.yaml diff --git a/docs/content/en/docs/implementing/assets/trace.png b/docs/content/en/docs/guides/assets/trace.png similarity index 100% rename from docs/content/en/docs/implementing/assets/trace.png rename to docs/content/en/docs/guides/assets/trace.png diff --git a/docs/content/en/docs/guides/auto-app-discovery.md b/docs/content/en/docs/guides/auto-app-discovery.md new file mode 100644 index 0000000000..c1e1b04a36 --- /dev/null +++ b/docs/content/en/docs/guides/auto-app-discovery.md @@ -0,0 +1,114 @@ +--- +title: Auto app discovery +description: Use Keptn automatic app discovery +weight: 100 +--- + +The automatically generated `KeptnApp` file +aggregates the workloads to include in the application, +based on annotations made to the workloads themselves. +This enables you to run Keptn observability features on your cluster. + +Afterward, you can monitor the status of the deployment using +a command like the following: + +```shell +kubectl get keptnworkloadversion -n podtato-kubectl -w +``` + +The generated `KeptnApp` file includes `metadata` +that names this `KeptnApp` and identifies the Namespace where it resides. + +```yaml +metadata: + name: simpleapp + namespace: simplenode-dev +``` + +It also includes a `spec.workloads` list +that defines the workloads to be included. + +Pre-/post-deployment tasks and evaluations for the `KeptnApp` +can also be added to this resource manually +but this is not required for observability. + +As an example, consider the following application, +consisting of multiple deployments, +which is going to be deployed into a Keptn-enabled namespace. +Note that: + +1. Keptn is enabled for the namespace where your application runs. +1. The `Deployment` workloads are annotated appropriately. + This example does not use other workloads. + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: podtato-kubectl + annotations: + keptn.sh/lifecycle-toolkit: "enabled" + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-frontend + namespace: podtato-kubectl +spec: + template: + metadata: + labels: + app.kubernetes.io/name: podtato-head-frontend + app.kubernetes.io/part-of: podtato-head + app.kubernetes.io/version: 0.1.0 + spec: + containers: + - name: podtato-head-frontend + image: podtato-head-frontend +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-hat + namespace: podtato-kubectl +spec: + replicas: 1 + template: + metadata: + labels: + app.kubernetes.io/name: podtato-head-hat + app.kubernetes.io/part-of: podtato-head + app.kubernetes.io/version: 0.1.1 + spec: + containers: + - name: podtato-head-hat + image: podtato-head-hat +``` + +Applying these resources results in the creation +of the following `KeptnApp` resource: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnApp +metadata: + name: podtato-head + namespace: podtato-kubectl + annotations: + app.kubernetes.io/managed-by: "keptn" +spec: + version: "" + workloads: + - name: podtato-head-frontend + version: 0.1.0 + - name: podtato-head-hat + version: 1.1.1 +``` + +With the `KeptnApp` resource created, +you get observability of your application's deployments +by using the OpenTelemetry tracing features +that are provided by Keptn: + +![Application deployment trace](../assets/trace.png) diff --git a/docs/content/en/docs/implementing/dora.md b/docs/content/en/docs/guides/dora.md similarity index 99% rename from docs/content/en/docs/implementing/dora.md rename to docs/content/en/docs/guides/dora.md index ed40e926b6..807a5a587e 100644 --- a/docs/content/en/docs/implementing/dora.md +++ b/docs/content/en/docs/guides/dora.md @@ -1,7 +1,7 @@ --- title: DORA metrics description: Access DORA metrics for your cluster -weight: 30 +weight: 1000 --- DORA metrics are an industry-standard set of measurements diff --git a/docs/content/en/docs/implementing/evaluatemetrics.md b/docs/content/en/docs/guides/evaluatemetrics.md similarity index 82% rename from docs/content/en/docs/implementing/evaluatemetrics.md rename to docs/content/en/docs/guides/evaluatemetrics.md index d995fa4c06..7fd25ff481 100644 --- a/docs/content/en/docs/implementing/evaluatemetrics.md +++ b/docs/content/en/docs/guides/evaluatemetrics.md @@ -1,7 +1,7 @@ --- title: Keptn Metrics description: Implement Keptn metrics -weight: 20 +weight: 300 --- The Keptn Metrics Operator provides a single entry point @@ -23,9 +23,9 @@ For an introduction to Keptn metrics, see Keptn metrics are implemented with two resources: -* [KeptnMetric](../yaml-crd-ref/metric.md) -- +* [KeptnMetric](../reference/crd-reference/metric.md) -- define the metric to report -* [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) -- +* [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) -- define the configuration for a data provider As soon as you define and apply @@ -36,7 +36,7 @@ You do not need to do anything else. ### Define KeptnMetricsProvider resources You must define a -[KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) resource +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource for each instance of each data provider you are using. Note the following: @@ -61,11 +61,11 @@ To configure a data provider into your Keptn cluster: into your Keptn cluster, following the instructions provided by the data source provider. See - [Prepare your cluster for Keptn](../install/k8s.md/#prepare-your-cluster-for-keptn) + [Prepare your cluster for Keptn](../installation/k8s.md/#prepare-your-cluster-for-keptn) for links. Keptn supports using multiple instances of multiple data providers. 1. Define a - [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource for each data source. For example, the `KeptnMetricProvider` resource @@ -102,7 +102,7 @@ spec: ### Define KeptnMetric information -The [KeptnMetric](../yaml-crd-ref/metric.md) resource +The [KeptnMetric](../reference/crd-reference/metric.md) resource defines the information you want to gather, specified as a query for the particular observability platform you are using. @@ -160,7 +160,7 @@ Note the following: ### Accessing Metrics via the Kubernetes Custom Metrics API `KeptnMetrics` can be retrieved using the `kubectl` command and the -[KeptnMetric](../yaml-crd-ref/metric.md) +[KeptnMetric](../reference/crd-reference/metric.md) API. This section shows how to do that. @@ -267,44 +267,3 @@ spec: range: interval: "3m" ``` - -## Using the HorizontalPodAutoscaler - -Use the Kubernetes Custom Metrics API -to refer to `KeptnMetric` via the -[Kubernetes HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) -(HPA), -as in the following example: - -```yaml -apiVersion: autoscaling/v2 -kind: HorizontalPodAutoscaler -metadata: - name: podtato-head-entry - namespace: podtato-kubectl -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: podtato-head-entry - minReplicas: 1 - maxReplicas: 10 - metrics: - - type: Object - object: - metric: - name: keptnmetric-sample - describedObject: - apiVersion: metrics.keptn.sh/v1beta1 - kind: KeptnMetric - name: keptnmetric-sample - target: - type: Value - value: "10" -``` - -See the -[Scaling Kubernetes Workloads based on Dynatrace Metrics](https://www.linkedin.com/pulse/scaling-kubernetes-workloads-based-dynatrace-metrics-keptnproject/) -blog post -for a detailed discussion of doing this with Dynatrace metrics. -The same approach could be used to implement HPA with other data providers. diff --git a/docs/content/en/docs/implementing/evaluations.md b/docs/content/en/docs/guides/evaluations.md similarity index 93% rename from docs/content/en/docs/implementing/evaluations.md rename to docs/content/en/docs/guides/evaluations.md index 4645f1fd21..70964d1c17 100644 --- a/docs/content/en/docs/implementing/evaluations.md +++ b/docs/content/en/docs/guides/evaluations.md @@ -1,11 +1,11 @@ --- title: Evaluations description: Understand Keptn evaluations and how to use them -weight: 150 +weight: 700 --- A -[KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resource contains a list of `objectives`, each of which checks whether a defined `KeptnMetric` resource meets a defined target value. @@ -19,7 +19,7 @@ so this evaluation ensures that more than 1 CPU is available before the [workload](https://kubernetes.io/docs/concepts/workloads/) or application is deployed. This evaluation references the -[KeptnMetric](../yaml-crd-ref/metric.md) resource +[KeptnMetric](../reference/crd-reference/metric.md) resource that is named `available-cpus`. This is defined in the example [metric.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/sample-app/base/metric.yaml) @@ -39,7 +39,7 @@ you must: to identify the `KeptnEvaluationDefinition` resource you want to run pre- and post-deployment for the specific [workloads](https://kubernetes.io/docs/concepts/workloads/). * Manually edit all - [KeptnApp](../yaml-crd-ref/app.md) resources + [KeptnApp](../reference/crd-reference/app.md) resources to specify the `KeptnEvaluationDefinition` to be run pre- and post-deployment evaluations for the `KeptnApp` itself. diff --git a/docs/content/en/docs/implementing/integrate.md b/docs/content/en/docs/guides/integrate.md similarity index 74% rename from docs/content/en/docs/implementing/integrate.md rename to docs/content/en/docs/guides/integrate.md index a13933a0b3..0046493e01 100644 --- a/docs/content/en/docs/implementing/integrate.md +++ b/docs/content/en/docs/guides/integrate.md @@ -1,7 +1,7 @@ --- -title: Integrate Keptn with your applications +title: Integrate Keptn with your Applications description: How to integrate Keptn into your Kubernetes cluster -weight: 10 +weight: 200 --- Keptn works @@ -20,7 +20,7 @@ to identify the workloads of interest. To integrate Keptn with your applications: * You must first -[install and enable](../install/install.md#basic-installation) +[install and enable](../installation/_index.md#basic-installation) Keptn. * Annotate or label your workloads with either Keptn or Kubernetes keys. @@ -33,7 +33,7 @@ with either Keptn or Kubernetes keys. Keptn uses these annotations to the Kubernetes workloads to create the [KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload) and -[KeptnApp](../yaml-crd-ref/app.md) +[KeptnApp](../reference/crd-reference/app.md) resources that it uses to provide observability and release lifecycle management. @@ -62,7 +62,7 @@ the `keptn.sh` or the `kubernetes` annotations/labels, it creates appropriate [KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload) and -[KeptnApp](../yaml-crd-ref/app.md) +[KeptnApp](../reference/crd-reference/app.md) resources for the version it detects. The basic keptn.sh keys that can be used for annotations or labels are: @@ -110,7 +110,7 @@ These keys are defined as: Note that there is no equivalent `app.kubernetes.io/` annotation/label for this label. 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: @@ -128,7 +128,7 @@ annotation/label is populated: but not the combined workloads that constitute your deployed application. See -[Keptn Applications and Keptn Workloads](../architecture/keptn-apps.md) +[Keptn Applications and Keptn Workloads](../components/lifecycle-operator/keptn-apps.md) for architectural information about how `KeptnApp` and `KeptnWorkloads` are implemented. @@ -179,19 +179,19 @@ that handles pre- and post-deployment evaluations and tasks, do the following: * Define the - [KeptnMetric](../yaml-crd-ref/metric.md) + [KeptnMetric](../reference/crd-reference/metric.md) and - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resources for each evaluation you want. A `KeptnEvaluationDefinition` compares the value of a `KeptnMetric` to the threshold that is specified. * You will also need to define the necessary - [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) and resource for each instance of each data source used for the `KeptnEvaluationDefinition` resources you define. * Define a - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resource for each task you want to execute. `KeptnTaskDefinition` resources contain re-usable "functions" that can execute before and after the deployment. @@ -211,7 +211,7 @@ do the following: to include each evaluation and task you want run for specific workloads. * Manually edit all - [KeptnApp](../yaml-crd-ref/app.md) resources + [KeptnApp](../reference/crd-reference/app.md) resources to specify evaluations and tasks to be run for the `KeptnApp` itself. ### Annotations to KeptnApp @@ -234,7 +234,7 @@ keptn.sh/post-deployment-tasks: <`TaskDefinition`-name> The value of these annotations corresponds to the name of Keptn [resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) called -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resources These resources contain re-usable "functions" that can execute before and after the deployment. @@ -247,117 +247,6 @@ until the infrastructure is capable of accepting deployments again. If everything is fine, the deployment continues and afterward, a Slack notification is sent with the result of the deployment -## Use Keptn automatic app discovery - -The automatically generated `KeptnApp` file -aggregates the workloads to include in the application, -based on annotations made to the workloads themselves. -This enables you to run Keptn observability features on your cluster. - -Afterward, you can monitor the status of the deployment using -a command like the following: - -```shell -kubectl get keptnworkloadversion -n podtato-kubectl -w -``` - -The generated `KeptnApp` file includes `metadata` -that names this `KeptnApp` and identifies the Namespace where it resides. - -```yaml -metadata: - name: simpleapp - namespace: simplenode-dev -``` - -It also includes a `spec.workloads` list -that defines the workloads to be included. - -Pre-/post-deployment tasks and evaluations for the `KeptnApp` -can also be added to this resource manually -but this is not required for observability. - -As an example, consider the following application, -consisting of multiple deployments, -which is going to be deployed into a Keptn-enabled namespace. -Note that: - -1. Keptn is enabled for the namespace where your application runs. -1. The `Deployment` workloads are annotated appropriately. - This example does not use other workloads. - -```yaml -apiVersion: v1 -kind: Namespace -metadata: - name: podtato-kubectl - annotations: - keptn.sh/lifecycle-toolkit: "enabled" - ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: podtato-head-frontend - namespace: podtato-kubectl -spec: - template: - metadata: - labels: - app.kubernetes.io/name: podtato-head-frontend - app.kubernetes.io/part-of: podtato-head - app.kubernetes.io/version: 0.1.0 - spec: - containers: - - name: podtato-head-frontend - image: podtato-head-frontend ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: podtato-head-hat - namespace: podtato-kubectl -spec: - replicas: 1 - template: - metadata: - labels: - app.kubernetes.io/name: podtato-head-hat - app.kubernetes.io/part-of: podtato-head - app.kubernetes.io/version: 0.1.1 - spec: - containers: - - name: podtato-head-hat - image: podtato-head-hat -``` - -Applying these resources results in the creation -of the following `KeptnApp` resource: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnApp -metadata: - name: podtato-head - namespace: podtato-kubectl - annotations: - app.kubernetes.io/managed-by: "keptn" -spec: - version: "" - workloads: - - name: podtato-head-frontend - version: 0.1.0 - - name: podtato-head-hat - version: 1.1.1 -``` - -With the `KeptnApp` resource created, -you get observability of your application's deployments -by using the OpenTelemetry tracing features -that are provided by Keptn: - -![Application deployment trace](../assets/trace.png) - ## Example of pre- and post-deployment actions A comprehensive example of pre- and post-deployment diff --git a/docs/content/en/docs/implementing/otel.md b/docs/content/en/docs/guides/otel.md similarity index 98% rename from docs/content/en/docs/implementing/otel.md rename to docs/content/en/docs/guides/otel.md index 3233f451b3..30c1ff4894 100644 --- a/docs/content/en/docs/implementing/otel.md +++ b/docs/content/en/docs/guides/otel.md @@ -1,7 +1,7 @@ --- title: OpenTelemetry observability description: How to standardize access to OpenTelemetry observability data -weight: 40 +weight: 1000 --- @@ -100,7 +100,7 @@ To integrate OpenTelemetry into Keptn: for the `Deployment` resource(s) to integrate Keptn into your Kubernetes cluster. - To expose OpenTelemetry metrics, - define a [KeptnConfig](../yaml-crd-ref/config.md) resource + define a [KeptnConfig](../reference/crd-reference/config.md) resource that has the `spec.OTelCollectorUrl` field populated with the URL of the OpenTelemetry collector. diff --git a/docs/content/en/docs/implementing/restart-application-deployment.md b/docs/content/en/docs/guides/restart-application-deployment.md similarity index 95% rename from docs/content/en/docs/implementing/restart-application-deployment.md rename to docs/content/en/docs/guides/restart-application-deployment.md index d5dea4e507..aff0111b4b 100644 --- a/docs/content/en/docs/implementing/restart-application-deployment.md +++ b/docs/content/en/docs/guides/restart-application-deployment.md @@ -1,16 +1,14 @@ --- -title: Restart an Application Deployment +title: Redeploy/Restart an Application description: Learn how to restart an unsuccessful Keptn Application Deployment. -layout: quickstart -weight: 100 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +weight: 600 --- -A [KeptnApp](../yaml-crd-ref/app.md) can fail +A [KeptnApp](../reference/crd-reference/app.md) can fail because of an unsuccessful pre-deployment evaluation or pre-deployment task. For example, this happens if the target value of a -[KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resource is misconfigured or a pre-deployment evaluation checks the wrong URL. diff --git a/docs/content/en/docs/implementing/slo.md b/docs/content/en/docs/guides/slo.md similarity index 94% rename from docs/content/en/docs/implementing/slo.md rename to docs/content/en/docs/guides/slo.md index 10c038f1e9..6ff8779085 100644 --- a/docs/content/en/docs/implementing/slo.md +++ b/docs/content/en/docs/guides/slo.md @@ -1,7 +1,7 @@ --- title: Analysis description: How to implement Keptn Analyses -weight: 60 +weight: 400 --- The Keptn Metrics Operator Analysis feature @@ -43,14 +43,14 @@ and can be displayed on dashboard tools, such as Grafana. > **Note** A preliminary release of the Keptn Analysis feature is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. See the - [Analysis](../yaml-crd-ref/analysis.md/#differences-between-versions) + [Analysis](../reference/crd-reference/analysis.md/#differences-between-versions) reference page for instructions to activate the preview of this feature. ## Keptn Analysis basics A Keptn Analysis is implemented with three resources: -* [AnalysisValueTemplate](../yaml-crd-ref/analysisvaluetemplate.md) +* [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) defines the SLI with the `KeptnMetricsProvider` (data source) and the query to perform for each SLI @@ -59,11 +59,11 @@ A Keptn Analysis is implemented with three resources: One `Analysis` can use data from multiple instances of multiple types of data provider; you must define a - [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource for each instance of each data provider you are using. The template refers to that provider and queries it. -* [AnalysisDefinition](../yaml-crd-ref/analysisdefinition.md) +* [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) define the list of SLOs for an `Analysis` An `AnalysisDefinition` resource contains a list of objectives to satisfy. @@ -77,7 +77,7 @@ A Keptn Analysis is implemented with three resources: defining the data provider from which to gather the data and how to compute the Analysis -* [Analysis](../yaml-crd-ref/analysis.md) +* [Analysis](../reference/crd-reference/analysis.md) define the specific configurations and the Analysis to report. An `Analysis` resource customizes the templates diff --git a/docs/content/en/docs/implementing/tasks.md b/docs/content/en/docs/guides/tasks.md similarity index 94% rename from docs/content/en/docs/implementing/tasks.md rename to docs/content/en/docs/guides/tasks.md index 88eee9fd11..6d2e2afb00 100644 --- a/docs/content/en/docs/implementing/tasks.md +++ b/docs/content/en/docs/guides/tasks.md @@ -1,17 +1,17 @@ --- title: Deployment tasks description: Learn how to work with Keptn tasks -weight: 90 +weight: 500 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- A -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md/) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md/) resource defines one or more "executables" (functions, programs, scripts, etc) that Keptn runs as part of the pre- and post-deployment phases of a -[KeptnApp](../yaml-crd-ref/app.md) or +[KeptnApp](../reference/crd-reference/app.md) or [KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload). - pre-deployment (before the pod is scheduled) @@ -33,7 +33,7 @@ A `KeptnTaskDefinition` includes calls to executables to be run. To implement a `KeptnTask`: - Define a - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resource that defines the runner to use for the container and the executables to be run pre- and post-deployment @@ -42,7 +42,7 @@ pre- and post-deployment if desired, creates a `KeptnApp` resource that consolidates multiple workloads into a single application - Annotate the appropriate - [KeptnApp](../yaml-crd-ref/app.md) + [KeptnApp](../reference/crd-reference/app.md) resource to associate your `KeptnTaskDefinition` with the pre- and post-deployment tasks that should be run; see @@ -104,7 +104,7 @@ can be configured in one of four different ways: resource that is populated with the function to execute See the -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) reference page for the synopsis and examples for each runner. ## Executing sequential tasks @@ -136,7 +136,7 @@ You have the following options: (either `deno-runtime` or `python-runtime`) to code the actual calls inline in the `KeptnTaskDefinition` resource. See - [Fields for pre-defined containers](../yaml-crd-ref/taskdefinition.md/#fields-for-pre-defined-containers) + [Fields for pre-defined containers](../reference/crd-reference/taskdefinition.md/#fields-for-pre-defined-containers) for more information. - Create a script that calls the functions, programs, and scripts @@ -147,7 +147,7 @@ You have the following options: which can set parameters for the script if appropriate. For more details about implementing these options, see the -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) page. ## Context @@ -160,7 +160,7 @@ For more information, see You may need to include context information in the `function` code included in the YAML file that defines a -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resource. For an example of how to do this, see the [keptn-tasks.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-tasks.yaml) diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md deleted file mode 100644 index 6a2fc2c522..0000000000 --- a/docs/content/en/docs/install/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Installation and Upgrade -description: Learn how to install and upgrade Keptn -weight: 30 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html ---- diff --git a/docs/content/en/docs/install/k8s.md b/docs/content/en/docs/install/k8s.md deleted file mode 100644 index ef19ff8d77..0000000000 --- a/docs/content/en/docs/install/k8s.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Kubernetes cluster -description: Bring or install a Kubernetes cluster -layout: quickstart -weight: 25 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html ---- - -Keptn is meant to be installed -into an existing Kubernetes cluster -that runs your deployment software. -See [Requirements](reqs.md) for information about supported releases -and advice about resources required. - -## Create local Kubernetes cluster - -You can also create a local cluster using packages such as -[KinD](https://kind.sigs.k8s.io/), -[k3d](https://k3d.io/), -[k3s](https://k3s.io/), -and [Minikube](https://minikube.sigs.k8s.io/docs/) -to set up a local, lightweight Kubernetes cluster -where you can install Keptn -for personal study, demonstrations, and testing. -For more information, see the Kubernetes -[Install Tools](https://kubernetes.io/docs/tasks/tools/) -documentation. - -The [Keptn Lifecycle Toolkit: Installation and KeptnTask Creation in Minutes](https://www.youtube.com/watch?v=Hh01bBwZ_qM) -video demonstrates how to create a KinD cluster. -on which you can install Keptn. -The basic steps are: - -1. Download, install, and run [Docker](https://docs.docker.com/get-docker/) -1. Download [KinD](https://kind.sigs.k8s.io/) -1. Create the local KinD cluster with the following command: - - ```shell - kind create cluster - ``` - - See the - [KinD Quick Start Guide](https://kind.sigs.k8s.io/docs/user/quick-start/) - for more information - -1. When the cluster has been created, - run the following to verify that the cluster is working - and that it is running a supported version of Kubernetes - with the following command: - - ```shell - kubectl version --short - ``` - -## Prepare your cluster for Keptn - -Keptn installs into an existing Kubernetes cluster. -When setting up a local Kubernetes cluster to study or demonstrate Keptn, -you need to provide these components. - -Your cluster should include the following: - -* A supported version of Kubernetes. - See [Supported Kubernetes versions](reqs.md/#supported-kubernetes-versions) - for details. - -* The - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) - CLI that is used to interact with Kubernetes clusters. - -* The - [Helm](https://helm.sh/docs/intro/install/) - CLI that is used to install and configure Keptn. - -* Deployment tools of your choice, - such as - [Argo CD](https://argo-cd.readthedocs.io/en/stable/) or - [Flux](https://fluxcd.io/). - Alternatively, Keptn also works with just `kubectl apply` for deployment. - -* At least one observability data provider such as - [Prometheus](https://prometheus.io/), - [Dynatrace](https://www.dynatrace.com/), - or [Datadog](https://www.datadoghq.com/); - you can use multiple instances of different data providers. - These provide: - - * Metrics used for - [Keptn Metrics](../implementing/evaluatemetrics.md/) - * Metrics used for - [OpenTelemetry](../implementing/otel.md/) - observability - * SLIs for pre- and post-deployment - [evaluations](../implementing/evaluations.md/) - * SLIs used for - [analyses](../implementing/slo.md) - -* If you want to use the standardized observability feature, - you must have an OpenTelemetry collector - as well as a Prometheus operator installed on your cluster. - For more information, see - [Requirements for OpenTelemetry](../implementing/otel.md/#requirements-for-opentelemetry). - -* If you want a dashboard for reviewing metrics and traces, - install the dashboard tools of your choice; - we primarily use Grafana. - For more information, see - [Requirements for Open Telemetry](../implementing/otel.md/#requirements-for-opentelemetry). - -* Keptn includes a lightweight `cert-manager` that, by default, - is installed as part of the Keptn software. - If you are using another certificate manager in the cluster, - you can configure Keptn to instead use your cert-manager. - See [Use Keptn with cert-manager.io](../operate/cert-manager.md) - for detailed instructions. - -## How many namespaces? - -You have significant flexibility to decide how many namespaces to use -and how to set them up. -See the Kubernetes -[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -documentation for some basic information. -You can also search and find many "Best Practices for Namespaces" -documents published on the web. - -Some considerations for Keptn: - -* Keptn primarily operates on Kubernetes - [Workload](https://kubernetes.io/docs/concepts/workloads/) - resources and - [KeptnApp](../yaml-crd-ref/app.md) - resources - that are activated and defined by annotations to each workload. -* [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) - resources need to be located - in the same namespace as the associated - [KeptnMetric](../yaml-crd-ref/metric.md) - resources. - But - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) - resources that are used for pre- and post-deployment - can reference metrics from any namespace. - So you can create `KeptnMetrics` in a centralized namespace - (such as `keptn-lifecycle-toolkit`) - and access those metrics in evaluations on all namespaces in the cluster. -* Analysis related resources - ([Analysis](../yaml-crd-ref/analysis.md), - [AnalysisDefinition](../yaml-crd-ref/analysisdefinition.md), - and - [AnalysisValueTemplate](../yaml-crd-ref/analysisvaluetemplate.md)) - reference each other via a `name` and, optionally, a `namespace` field. - The `Analysis` resource references the `AnalysisDefinition` resource, - which then references the `AnalysisValueTemplate` resources. - - * If the `namespace` in the reference is not set explicitly, - the `AnalysisDefinition` and `AnalysisValueTemplate` resources - must reside in the same namespace as the `Analysis` resource. - * If the `namespace` in the reference is set for the resources, - the `Analysis`, `AnalysisDefinition`, and `AnalysisValueTemplate` resources - can each reside in different namespaces. - - This provides configuration options such as the following: - - * You can have one namespace - with all of your `AnalysisDefinition` and `AnalysisValueTemplate` resources - and reuse them in the different namespaces where you run analyses. - - * You can have everything strictly namespaced - and always put the `AnalysisDefinition`, `AnalysisValueTemplate` - and the `Analysis` resources into the same namespace, - without adding the explicit namespace selectors - when creating references between those objects. - -* Each `KeptnApp` resource identifies the namespace to which it belongs. - If you configure multiple namespaces, - you can have `KeptnApp` resources with the same name - in multiple namespaces without having them conflict. -* You do not need separate namespaces for separate versions of your application. - The `KeptnApp` resource includes fields to define - the `version` as well as a `revision` - (used if you have to rerun a deployment - but want to retain the version number). - -So, possible namespace designs run the gamut: - -* Run all your Keptn work in a single namespace -* Create a separate namespace for each logical grouping of your Keptn work -* Create a separate namespace for each [workload](https://kubernetes.io/docs/concepts/workloads/) diff --git a/docs/content/en/docs/install/reqs.md b/docs/content/en/docs/install/reqs.md deleted file mode 100644 index 3f11381417..0000000000 --- a/docs/content/en/docs/install/reqs.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Requirements -description: Supported software versions and information about resources required -weight: 15 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html ---- - -## Supported Kubernetes versions - -Keptn requires Kubernetes v1.24.0 or later. - -Run the following to ensure that both client and server versions -are running Kubernetes versions greater than or equal to v1.24. -In this example, both client and server are at v1.24.0 -so Keptn will work. - -```shell -kubectl version --short -``` - -```shell -Client Version: v1.24.0 -Kustomize Version: v4.5.4 -Server Version: v1.24.0 -``` - -Keptn makes use of a custom scheduler -when running on Kubernetes v1.26 and earlier. -For Kubernetes v1.27 and later, scheduling is -implemented using -[Kubernetes scheduling gates](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness/), -unless the `schedulingGatesEnabled` Helm value is set to `false`. -See -[Keptn integration with Scheduling](../architecture/components/scheduler.md) -for details. - -If Keptn is installed on a [vCluster](https://www.vcluster.com/) with -Kubernetes v1.26 or earlier, some extra configuration -needs to be added for full compatibility. -See -[Running Keptn with vCluster](#running-keptn-with-vcluster) -for more information. - -## Running Keptn with vCluster - -Keptn running on Kubernetes versions 1.26 and older -uses a custom -[scheduler](../architecture/components/scheduler.md), -so it does not work with -[Virtual Kubernetes Clusters](https://www.vcluster.com/) -("vClusters") out of the box. -This is also an issue -if the `lifecycleOperator.schedulingGatesEnabled` Helm value is set to `false` -for Kubernetes version 1.27 and later. -See -[Keptn integration with Scheduling](../architecture/components/scheduler.md) -for details. - -To solve this problem: - -1. Follow the instructions in - [Separate vCluster Scheduler](https://www.vcluster.com/docs/architecture/scheduling#separate-vcluster-scheduler) - to modify the vCluster `values.yaml` file - to use a virtual scheduler. - -1. Create or upgrade the vCluster, - following the instructions in that same document. - -1. Follow the instructions in the section below - to install Keptn in that vCluster. diff --git a/docs/content/en/docs/install/install.md b/docs/content/en/docs/installation/_index.md similarity index 72% rename from docs/content/en/docs/install/install.md rename to docs/content/en/docs/installation/_index.md index 716a6bb5b7..3a61599fb0 100644 --- a/docs/content/en/docs/install/install.md +++ b/docs/content/en/docs/installation/_index.md @@ -1,7 +1,7 @@ --- -title: Install Keptn +title: Installation description: Install and enable Keptn -weight: 35 +weight: 30 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- @@ -17,7 +17,43 @@ Keptn v0.9.0 and later is installed using [Helm](https://helm.sh/). > if you need to upgrade from a manifest installation. After you install Keptn, you are ready to -[Integrate Keptn with your applications](../implementing/integrate.md). +[Integrate Keptn with your applications](../guides/integrate.md). + +## Supported Kubernetes versions + +Keptn requires Kubernetes v1.24.0 or later. + +Run the following to ensure that both client and server versions +are running Kubernetes versions greater than or equal to v1.24. +In this example, both client and server are at v1.24.0 +so Keptn will work. + +```shell +kubectl version --short +``` + +```shell +Client Version: v1.24.0 +Kustomize Version: v4.5.4 +Server Version: v1.24.0 +``` + +Keptn makes use of a custom scheduler +when running on Kubernetes v1.26 and earlier. +For Kubernetes v1.27 and later, scheduling is +implemented using +[Kubernetes scheduling gates](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness/), +unless the `schedulingGatesEnabled` Helm value is set to `false`. +See +[Keptn integration with Scheduling](../components/scheduling/_index.md) +for details. + +If Keptn is installed on a [vCluster](https://www.vcluster.com/) with +Kubernetes v1.26 or earlier, some extra configuration +needs to be added for full compatibility. +See +[Running Keptn with vCluster](./configuration/vcluster.md) +for more information. ## Basic installation @@ -26,12 +62,6 @@ using a Helm chart. To modify the Keptn configuration, you must modify the `values.yaml` file of the chart. -> **Note** Keptn works on virtually any type of Kubernetes cluster. - See - [Requirements](reqs.md) - for specific requirements for your Kubernetes cluster. -> - The command sequence to fetch and install the latest release of Keptn is: ```shell @@ -68,7 +98,7 @@ Some helpful hints: ```shell helm search repo keptn --versions ``` - + You see that the "CHART VERSION" for `keptn/keptn` v0.9.0 is 0.3.0 so use the following command to explicitly installs Keptn v0.9.0: @@ -112,12 +142,12 @@ The following table summarizes the Keptn `values.yaml` files. * The "Configuration file" column leads you to the Helm values files for each component -| Component | Used for | Configuration file | -|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| --------------------| -| [Keptn](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/README.md) | Installs subcharts, global configuration | [keptn/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) | -| [lifecycle-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/README.md) | [Observability](../implementing/otel.md), [Release Lifecycle Management](../intro/_index.md#release-lifecycle-management) | [keptn-lifecycle-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/values.yaml) | -| [metrics-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/README.md) | [Keptn metrics](../implementing/evaluatemetrics.md), [Analysis](../implementing/slo.md) | [keptn-metrics-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/values.yaml) | -| [cert-manager](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md) | [TLS Certificate management for all Keptn components](../architecture/cert-manager.md) | [keptn-cert-manager/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/values.yaml) | +| Component | Used for | Configuration file | +|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| --------------------| +| [Keptn](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/README.md) | Installs subcharts, global configuration | [keptn/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) | +| [lifecycle-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/README.md) | [Observability](../guides/otel.md), [Release Lifecycle Management](../core-concepts/_index.md#release-lifecycle-management) | [keptn-lifecycle-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/values.yaml) | +| [metrics-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/README.md) | [Keptn metrics](../guides/evaluatemetrics.md), [Analysis](../guides/slo.md) | [keptn-metrics-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/values.yaml) | +| [cert-manager](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md) | [TLS Certificate management for all Keptn components](../components/certificate-operator/_index.md) | [keptn-cert-manager/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/values.yaml) | ## Customizing the configuration of components @@ -127,7 +157,7 @@ Use the subcomponent's parent value as the root for your configuration. Here is an example `values.yaml` altering global and metrics operator values: -{{< docsembed path="content/en/docs/install/assets/values-advance-changes.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-advance-changes.yaml" >}} Note the additional values that are specified in the `metricsOperator` section. @@ -200,10 +230,10 @@ If you wish to use your custom certificate manager, you can disable Keptn `cert-manager` by setting the `certificateManager.enabled` Helm value to `false`: -{{< docsembed path="content/en/docs/install/assets/values-remove-certmanager.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-remove-certmanager.yaml" >}} For more information on using `cert-manager` with Keptn, see -[Use Keptn with cert-manager.io](../operate/cert-manager.md). +[Use Keptn with cert-manager.io](../components/certificate-operator/_index.md). For the full list of Helm values, see the [keptn-cert-manager Helm chart README](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md). diff --git a/docs/content/en/docs/install/assets/values-advance-changes.yaml b/docs/content/en/docs/installation/assets/values-advance-changes.yaml similarity index 100% rename from docs/content/en/docs/install/assets/values-advance-changes.yaml rename to docs/content/en/docs/installation/assets/values-advance-changes.yaml diff --git a/docs/content/en/docs/install/assets/values-only-lifecycle.yaml b/docs/content/en/docs/installation/assets/values-only-lifecycle.yaml similarity index 100% rename from docs/content/en/docs/install/assets/values-only-lifecycle.yaml rename to docs/content/en/docs/installation/assets/values-only-lifecycle.yaml diff --git a/docs/content/en/docs/install/assets/values-only-metrics.yaml b/docs/content/en/docs/installation/assets/values-only-metrics.yaml similarity index 100% rename from docs/content/en/docs/install/assets/values-only-metrics.yaml rename to docs/content/en/docs/installation/assets/values-only-metrics.yaml diff --git a/docs/content/en/docs/install/assets/values-remove-certmanager.yaml b/docs/content/en/docs/installation/assets/values-remove-certmanager.yaml similarity index 100% rename from docs/content/en/docs/install/assets/values-remove-certmanager.yaml rename to docs/content/en/docs/installation/assets/values-remove-certmanager.yaml diff --git a/docs/content/en/docs/installation/configuration/_index.md b/docs/content/en/docs/installation/configuration/_index.md new file mode 100644 index 0000000000..2eda9cdf8f --- /dev/null +++ b/docs/content/en/docs/installation/configuration/_index.md @@ -0,0 +1,5 @@ +--- +title: Configuration +description: Configuration +weight: 30 +--- diff --git a/docs/content/en/docs/operate/cert-manager.md b/docs/content/en/docs/installation/configuration/cert-manager.md similarity index 91% rename from docs/content/en/docs/operate/cert-manager.md rename to docs/content/en/docs/installation/configuration/cert-manager.md index 2b3e8f4a5a..aad2638cb0 100644 --- a/docs/content/en/docs/operate/cert-manager.md +++ b/docs/content/en/docs/installation/configuration/cert-manager.md @@ -1,10 +1,10 @@ --- -title: Use Keptn with cert-manager.io (optional) +title: Keptn + cert-manager.io description: Replace the default Keptn cert-manager weight: 30 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- + Keptn includes a light-weight, customized cert-manager that is used to register Webhooks to the [KubeAPI](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). @@ -12,7 +12,7 @@ Bundling the cert-manager simplifies the installation for new users and provides the functionality Keptn needs without the overhead of other cert-managers. For a description of the architecture, see -[Keptn Certificate Manager](../architecture/cert-manager.md). +[Keptn Certificate Manager](../../components/certificate-operator/_index.md). Keptn also works well with `cert-manager.io`. If you are already using `cert-manager.io`, diff --git a/docs/content/en/docs/installation/configuration/namespace.md b/docs/content/en/docs/installation/configuration/namespace.md new file mode 100644 index 0000000000..011697f32f --- /dev/null +++ b/docs/content/en/docs/installation/configuration/namespace.md @@ -0,0 +1,78 @@ +--- +title: How to structure your namespaces +description: +weight: 10 +--- + +You have significant flexibility to decide how many namespaces to use +and how to set them up. +See the Kubernetes +[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +documentation for some basic information. +You can also search and find many "Best Practices for Namespaces" +documents published on the web. + +Some considerations for Keptn: + +* Keptn primarily operates on Kubernetes + [Workload](https://kubernetes.io/docs/concepts/workloads/) + resources and + [KeptnApp](../../reference/crd-reference/app.md) + [KeptnApp](../../reference/crd-reference/app.md) + resources + that are activated and defined by annotations to each workload. +* [KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md) + resources need to be located + in the same namespace as the associated + [KeptnMetric](../../reference/crd-reference/metric.md) + resources. + But + [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md) + resources that are used for pre- and post-deployment + can reference metrics from any namespace. + So you can create `KeptnMetrics` in a centralized namespace + (such as `keptn-lifecycle-toolkit`) + and access those metrics in evaluations on all namespaces in the cluster. +* Analysis related resources + ([Analysis](../../reference/crd-reference/analysis.md), + [AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md), + and + [AnalysisValueTemplate](../../reference/crd-reference/analysisvaluetemplate.md)) + reference each other via a `name` and, optionally, a `namespace` field. + The `Analysis` resource references the `AnalysisDefinition` resource, + which then references the `AnalysisValueTemplate` resources. + + * If the `namespace` in the reference is not set explicitly, + the `AnalysisDefinition` and `AnalysisValueTemplate` resources + must reside in the same namespace as the `Analysis` resource. + * If the `namespace` in the reference is set for the resources, + the `Analysis`, `AnalysisDefinition`, and `AnalysisValueTemplate` resources + can each reside in different namespaces. + + This provides configuration options such as the following: + + * You can have one namespace + with all of your `AnalysisDefinition` and `AnalysisValueTemplate` resources + and reuse them in the different namespaces where you run analyses. + + * You can have everything strictly namespaced + and always put the `AnalysisDefinition`, `AnalysisValueTemplate` + and the `Analysis` resources into the same namespace, + without adding the explicit namespace selectors + when creating references between those objects. + +* Each `KeptnApp` resource identifies the namespace to which it belongs. + If you configure multiple namespaces, + you can have `KeptnApp` resources with the same name + in multiple namespaces without having them conflict. +* You do not need separate namespaces for separate versions of your application. + The `KeptnApp` resource includes fields to define + the `version` as well as a `revision` + (used if you have to rerun a deployment + but want to retain the version number). + +So, possible namespace designs run the gamut: + +* Run all your Keptn work in a single namespace +* Create a separate namespace for each logical grouping of your Keptn work +* Create a separate namespace for each [workload](https://kubernetes.io/docs/concepts/workloads/) diff --git a/docs/content/en/docs/installation/configuration/vcluster.md b/docs/content/en/docs/installation/configuration/vcluster.md new file mode 100644 index 0000000000..d1443c8d2a --- /dev/null +++ b/docs/content/en/docs/installation/configuration/vcluster.md @@ -0,0 +1,31 @@ +--- +title: vCluster installation +description: Running Keptn with vCluster +weight: 20 +--- + +Keptn running on Kubernetes versions 1.26 and older +uses a custom +[scheduler](../../components/scheduling/_index.md), +so it does not work with +[Virtual Kubernetes Clusters](https://www.vcluster.com/) +("vClusters") out of the box. +This is also an issue +if the `lifecycleOperator.schedulingGatesEnabled` Helm value is set to `false` +for Kubernetes version 1.27 and later. +See +[Keptn integration with Scheduling](../../components/scheduling/_index.md) +for details. + +To solve this problem: + +1. Follow the instructions in + [Separate vCluster Scheduler](https://www.vcluster.com/docs/architecture/scheduling#separate-vcluster-scheduler) + to modify the vCluster `values.yaml` file + to use a virtual scheduler. + +1. Create or upgrade the vCluster, + following the instructions in that same document. + +1. Follow the instructions in the section below + to install Keptn in that vCluster. diff --git a/docs/content/en/docs/installation/k8s.md b/docs/content/en/docs/installation/k8s.md new file mode 100644 index 0000000000..25af548131 --- /dev/null +++ b/docs/content/en/docs/installation/k8s.md @@ -0,0 +1,115 @@ +--- +title: Kubernetes cluster +description: Bring or install a Kubernetes cluster +layout: quickstart +weight: 1000 +hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +--- + +Keptn is meant to be installed +into an existing Kubernetes cluster +that runs your deployment software. +See [Requirements](_index.md#supported-kubernetes-versions) for information about supported releases +and advice about resources required. + +## Create local Kubernetes cluster + +You can also create a local cluster using packages such as +[KinD](https://kind.sigs.k8s.io/), +[k3d](https://k3d.io/), +[k3s](https://k3s.io/), +and [Minikube](https://minikube.sigs.k8s.io/docs/) +to set up a local, lightweight Kubernetes cluster +where you can install Keptn +for personal study, demonstrations, and testing. +For more information, see the Kubernetes +[Install Tools](https://kubernetes.io/docs/tasks/tools/) +documentation. + +The [Keptn Lifecycle Toolkit: Installation and KeptnTask Creation in Minutes](https://www.youtube.com/watch?v=Hh01bBwZ_qM) +video demonstrates how to create a KinD cluster. +on which you can install Keptn. +The basic steps are: + +1. Download, install, and run [Docker](https://docs.docker.com/get-docker/) +1. Download [KinD](https://kind.sigs.k8s.io/) +1. Create the local KinD cluster with the following command: + + ```shell + kind create cluster + ``` + + See the + [KinD Quick Start Guide](https://kind.sigs.k8s.io/docs/user/quick-start/) + for more information + +1. When the cluster has been created, + run the following to verify that the cluster is working + and that it is running a supported version of Kubernetes + with the following command: + + ```shell + kubectl version --short + ``` + +## Prepare your cluster for Keptn + +Keptn installs into an existing Kubernetes cluster. +When setting up a local Kubernetes cluster to study or demonstrate Keptn, +you need to provide these components. + +Your cluster should include the following: + +* A supported version of Kubernetes. + See [Supported Kubernetes versions](_index.md#supported-kubernetes-versions) + for details. + +* The + [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) + CLI that is used to interact with Kubernetes clusters. + +* The + [Helm](https://helm.sh/docs/intro/install/) + CLI that is used to install and configure Keptn. + +* Deployment tools of your choice, + such as + [Argo CD](https://argo-cd.readthedocs.io/en/stable/) or + [Flux](https://fluxcd.io/). + Alternatively, Keptn also works with just `kubectl apply` for deployment. + +* At least one observability data provider such as + [Prometheus](https://prometheus.io/), + [Dynatrace](https://www.dynatrace.com/), + or [Datadog](https://www.datadoghq.com/); + you can use multiple instances of different data providers. + These provide: + + * Metrics used for + [Keptn Metrics](../guides/evaluatemetrics.md/) + * Metrics used for + [OpenTelemetry](../guides/otel.md/) + observability + * SLIs for pre- and post-deployment + [evaluations](../guides/evaluations.md/) + * SLIs used for + [analyses](../guides/slo.md) + +* If you want to use the standardized observability feature, + you must have an OpenTelemetry collector + as well as a Prometheus operator installed on your cluster. + For more information, see + [Requirements for OpenTelemetry](../guides/otel.md/#requirements-for-opentelemetry). + +* If you want a dashboard for reviewing metrics and traces, + install the dashboard tools of your choice; + we primarily use Grafana. + For more information, see + [Requirements for Open Telemetry](../guides/otel.md/#requirements-for-opentelemetry). + +* Keptn includes a lightweight `cert-manager` that, by default, + is installed as part of the Keptn software. + If you are using another certificate manager in the cluster, + you can configure Keptn to instead use your cert-manager. + See [Use Keptn with cert-manager.io](./configuration/cert-manager.md) + for detailed instructions. diff --git a/docs/content/en/docs/install/tips-tricks.md b/docs/content/en/docs/installation/tips-tricks.md similarity index 78% rename from docs/content/en/docs/install/tips-tricks.md rename to docs/content/en/docs/installation/tips-tricks.md index 2a75a80df4..6e16d4ec7e 100644 --- a/docs/content/en/docs/install/tips-tricks.md +++ b/docs/content/en/docs/installation/tips-tricks.md @@ -6,7 +6,7 @@ hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.htm --- The -[Install Keptn](install.md) +[Install Keptn](_index.md) page documents how to install Keptn. This page provides some background and more examples that supplement that information. @@ -25,7 +25,7 @@ umbrella Helm chart. Each subchart has its own README file describing possible configuration options, but configuration changes for the subcharts are added to a single `values.yaml` file. See -[Customizing the configuration of components](install.md/#customizing-the-configuration-of-components) +[Customizing the configuration of components](_index.md#customizing-the-configuration-of-components) for an example. ## Installing older versions of Keptn @@ -42,7 +42,8 @@ compared to the installation of earlier releases: To install a version prior to v0.9.0, use the install command sequence that is documented for that release. To install the latest version, use the installation commands on the -[Install Keptn](install.md/#basic-installation) +[Install Keptn](_index.md#basic-installation) +[Install Keptn](_index.md#basic-installation) page. To install an older release, @@ -51,7 +52,7 @@ in the `helm upgrade --install` command for the release you are installing. ## Example configurations by use-case -[Control what components are installed](install.md/#customizing-the-configuration-of-components) +[Control what components are installed](_index.md#customizing-the-configuration-of-components) discusses how to configure Keptn to include only the components you want. The following sections summarize and give examples of the configurations needed for different use cases. @@ -64,10 +65,10 @@ you do not need to install the Keptn Metrics Operator. To disable it, set the `metricsOperator.enabled` value to `false` as in the following: -{{< embed path="/docs/content/en/docs/install/assets/values-only-lifecycle.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-only-lifecycle.yaml" >}} Note that, if you want to run pre- and/or post-deployment -[evaluations](../implementing/evaluations.md) +[evaluations](../guides/evaluations.md) as part of the Release Lifecycle use-case, you need to have the Keptn Metrics Operator installed. @@ -93,15 +94,15 @@ You see the annotation line `keptn.sh/lifecycle-toolkit: "enabled"`. After enabling Keptn for your namespace(s), you are ready to -[Integrate Keptn with your applications](../implementing/integrate.md). +[Integrate Keptn with your applications](../guides/integrate.md). For more information about implementing Observability, see the -[Observability User Guide](../implementing/otel.md). +[Observability User Guide](../guides/otel.md). For more information about implementing Keptn Release Lifecycle, see the -[Deployment tasks](../implementing/tasks.md) +[Deployment tasks](../guides/tasks.md) and -[Evaluations](../implementing/evaluations.md) +[Evaluations](../guides/evaluations.md) User Guides. ### Enable Keptn Metrics Operator (Metrics) @@ -110,10 +111,10 @@ If you are only interested in Metrics, you do not need the Keptn Lifecycle Operator. Disable it using the following values.yaml: -{{< embed path="/docs/content/en/docs/install/assets/values-only-metrics.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-only-metrics.yaml" >}} For more information about implementing Metrics, see the -[Metrics User Guide](../implementing/evaluatemetrics.md). +[Metrics User Guide](../guides/evaluatemetrics.md). ### Enable Keptn Analysis (SLOs/SLIs) @@ -121,17 +122,17 @@ To enable Keptn Analysis in your cluster, you again do not need the Keptn Lifcycle Operator. Disable it using the following values.yaml: -{{< embed path="/docs/content/en/docs/install/assets/values-only-metrics.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-only-metrics.yaml" >}} > **Note** A preliminary release of the Keptn Analysis feature is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. See the - [Analysis](../yaml-crd-ref/analysis.md/#differences-between-versions) + [Analysis](../reference/crd-reference/analysis.md/#differences-between-versions) reference page for how to activate the preview of this feature. > For more information about implementing Keptn Analysis, see the -[Analysis User Guide](../implementing/slo.md). +[Analysis User Guide](../guides/slo.md). ### Disable Keptn Certificate Manager (Certificates) @@ -141,7 +142,7 @@ you can disable the Keptn `cert-manager` by using the to the `helm upgrade` command line or you can modify the `values.yaml` file: -{{< embed path="/docs/content/en/docs/install/assets/values-remove-certmanager.yaml" >}} +{{< docsembed path="content/en/docs/installation/assets/values-remove-certmanager.yaml" >}} For more information about using `cert-manager` with Keptn, see -[Use Keptn with cert-manager.io](../operate/cert-manager.md). +[Use Keptn with cert-manager.io](./configuration/cert-manager.md). diff --git a/docs/content/en/docs/install/troubleshooting.md b/docs/content/en/docs/installation/troubleshooting.md similarity index 98% rename from docs/content/en/docs/install/troubleshooting.md rename to docs/content/en/docs/installation/troubleshooting.md index d068412039..9998fbed82 100644 --- a/docs/content/en/docs/install/troubleshooting.md +++ b/docs/content/en/docs/installation/troubleshooting.md @@ -16,7 +16,7 @@ Below are some common problems and their solutions: If you are facing an issue where Keptn is installed but does not seem to be aware of your [workloads](https://kubernetes.io/docs/concepts/workloads/), follow these steps: -1. Ensure that the namespace you wish to target is [annotated correctly](install.md#basic-installation). +1. Ensure that the namespace you wish to target is [annotated correctly](_index.md#basic-installation). 2. Make sure your [workloads](https://kubernetes.io/docs/concepts/workloads/) (e.g., Deployment manifests) have the [three required annotations](https://lifecycle.keptn.sh/docs/implementing/integrate/#annotate-workloads). diff --git a/docs/content/en/docs/install/upgrade.md b/docs/content/en/docs/installation/upgrade.md similarity index 97% rename from docs/content/en/docs/install/upgrade.md rename to docs/content/en/docs/installation/upgrade.md index d58083d127..b8fd4fdb9b 100644 --- a/docs/content/en/docs/install/upgrade.md +++ b/docs/content/en/docs/installation/upgrade.md @@ -2,7 +2,7 @@ title: Upgrade description: How to upgrade to the latest version of Keptn layout: quickstart -weight: 45 +weight: 10 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- @@ -19,7 +19,7 @@ helm upgrade --install keptn klt/klt \ Use the `--set` flag or download and edit the `values.yaml` file to modify the configuration as discussed on the -[Install Keptn](../install/) page. +[Install Keptn](/) page. > **Warning** If you installed your Keptn instance from the Manifest, @@ -63,7 +63,7 @@ helm upgrade --install keptn klt/klt -n keptn-lifecycle-toolkit-system --create- ``` For information about advanced installation options, refer to -[Modify Helm configuration options](install.md). +[Modify Helm configuration options](_index.md). 1. After the installation finishes, restore the manifests from you backup diff --git a/docs/content/en/docs/migrate/metrics-observe.md b/docs/content/en/docs/migrate/metrics-observe.md index 416541a8ab..a2c8982e0c 100644 --- a/docs/content/en/docs/migrate/metrics-observe.md +++ b/docs/content/en/docs/migrate/metrics-observe.md @@ -7,23 +7,23 @@ weight: 40 The SLIs and SLOs used for Keptn v1 quality gates can be ported to appropriate Keptn facilities: -* [Keptn Metrics](../implementing/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](../implementing/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://keptn.sh/docs/1.0.x/reference/files/sli/) and [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) files into - [KeptnEvaluationDefinition](../yaml-crd-ref/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](../implementing/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](../implementing/dora.md) -* [OpenTelemetry observability](../implementing/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](../yaml-crd-ref/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](../implementing/evaluations.md). +[Keptn Evaluations](../guides/evaluations.md). To implement this: * Transfer the information from the Keptn v1 [sli.yaml](https://keptn.sh/docs/1.0.x/reference/files/sli/) files into - [KeptnMetric](../yaml-crd-ref/metric.md) resources + [KeptnMetric](../reference/crd-reference/metric.md) resources * Transfer the information from the Keptn v1 [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) files into - [KeptnEvaluationDefinition](../yaml-crd-ref/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://keptn.sh/docs/1.0.x/reference/files/sli/) file to a Keptn - [AnalysisValueTemplate](../yaml-crd-ref/analysisvaluetemplate.md) + [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) resource: @@ -143,7 +143,7 @@ The process is: The process of converting the Keptn v1 [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) files to - [AnalysisDefinition](../yaml-crd-ref/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 @@ The process is: 1. Create a `KeptnMetricsProvider` resource - A [KeptnMetricsProvider](../yaml-crd-ref/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 @@ The process is: Create a yaml file (such as `analysis-instance.yaml`) to populate the - [Analysis](../yaml-crd-ref/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/content/en/docs/migrate/strategy.md b/docs/content/en/docs/migrate/strategy.md index f692bc0af8..55e276b703 100644 --- a/docs/content/en/docs/migrate/strategy.md +++ b/docs/content/en/docs/migrate/strategy.md @@ -18,7 +18,7 @@ we suggest that you run through the exercises in to familiarize yourself with how Keptn works. When you are ready to begin the migration, follow the instructions in -[Installation and upgrade](../install) +[Installation and upgrade](../installation) to set up your Kubernetes cluster and install Keptn on it. @@ -44,7 +44,9 @@ Some key points: [shipyard.yaml](https://keptn.sh/docs/1.0.x/reference/files/shipyard/) file as Keptn v1 does. * See the - [CRD Reference](../yaml-crd-ref) + [Lifecycle CRD Reference](../reference/crd-reference) + and + [Metrics CRD Reference](../reference/crd-reference) section for pages that describe the Keptn manifests that you populate manually for Keptn. * See the @@ -61,7 +63,7 @@ Some key points: the user-defined requirements. * Keptn operates on a - [KeptnApp](../yaml-crd-ref/app.md) + [KeptnApp](../reference/crd-reference/app.md) resource that is an amalgamation of multiple Kubernetes workloads, which together comprise the released application. @@ -93,7 +95,7 @@ Some key points: For in-depth information about Keptn components and how they work, see the -[Architecture](../architecture) +[Architecture](../components) section. ## Disposition of Keptn v1 components in Keptn @@ -138,10 +140,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](../yaml-crd-ref/app.md) +[KeptnTaskDefinition](../reference/crd-reference/app.md) or other resources. See -[Working with Keptn tasks](../implementing/tasks.md) +[Working with Keptn tasks](../guides/tasks.md) for more information. For example: @@ -169,7 +171,7 @@ when architecting the migration: * A **deployment stage** -- may define sequences of tasks that should be translated into - [KeptnTaskDefinition](../yaml-crd-ref/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 @@ -198,7 +200,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](../yaml-crd-ref/taskdefinition.md) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) resources that are defined to run either pre- or post-deployment of the pod-scheduling phase. @@ -232,13 +234,13 @@ that is appropriate for the activity: or [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), workload. You can code - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) and - [KeptnEvaluationDefinition](../yaml-crd-ref/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](../yaml-crd-ref/evaluationdefinition.md) + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resource. * All other standard tasks (**action**, **approval**, **get-action**, **rollback**, @@ -270,7 +272,7 @@ such as Prometheus, Dynatrace, or Datadog, which is configured as a Keptn integration. When migrating to Keptn, you need to define a -[KeptnMetricsProvider](../yaml-crd-ref/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 @@ -279,18 +281,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](../yaml-crd-ref/metric.md) +* [KeptnMetric](../reference/crd-reference/metric.md) resources to do - [evaluations](../implementing/evaluations.md) + [evaluations](../guides/evaluations.md) with - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) resources. -* [AnalysisValueTemplate](../yaml-crd-ref/analysisvaluetemplate.md) +* [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) resources to do - [analyses](../implementing/slo.md) + [analyses](../guides/slo.md) with - [AnalysisDefinition](../yaml-crd-ref/analysisdefinition.md) + [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) resources. Tools are provided to convert Keptn v1 SLIs and SLOs to Keptn resources; see @@ -304,17 +306,17 @@ Keptn v1 can be implemented on Keptn as evaluations or analyses: * Simple evaluations of an SLI can be implemented as - [Evaluations](../implementing/evaluations.md) + [Evaluations](../guides/evaluations.md) which are defined as - [KeptnEvaluationDefinition](../yaml-crd-ref/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](../implementing/slo.md) + [Analyses](../guides/slo.md) that are defined in - [AnalysisDefinition](../yaml-crd-ref/analysisdefinition.md) + [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) resources. Tools are provided to convert Keptn v1 SLIs and SLOs to Keptn resources; see @@ -339,7 +341,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](../implementing/evaluatemetrics.md/#using-the-horizontalpodautoscaler) + [Using the HorizontalPodAutoscaler](../use-cases/hpa.md) for more information. ### Integrations and services in JES @@ -349,7 +351,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](../yaml-crd-ref/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/docs/content/en/docs/operate/_index.md b/docs/content/en/docs/operate/_index.md deleted file mode 100644 index 1caf982eed..0000000000 --- a/docs/content/en/docs/operate/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Operate Keptn -description: This section contains various content on operating Keptn day-to-day -weight: 30 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html ---- \ No newline at end of file diff --git a/docs/content/en/docs/reference/_index.md b/docs/content/en/docs/reference/_index.md new file mode 100644 index 0000000000..6756f51793 --- /dev/null +++ b/docs/content/en/docs/reference/_index.md @@ -0,0 +1,7 @@ +--- +title: Reference +description: Reference pages for Keptn +weight: 800 +--- + +This section of the Keptn documentation contains reference documentation. diff --git a/docs/content/en/docs/yaml-crd-ref/_index.md b/docs/content/en/docs/reference/crd-reference/_index.md similarity index 97% rename from docs/content/en/docs/yaml-crd-ref/_index.md rename to docs/content/en/docs/reference/crd-reference/_index.md index 0c97fcb83a..6222503957 100644 --- a/docs/content/en/docs/yaml-crd-ref/_index.md +++ b/docs/content/en/docs/reference/crd-reference/_index.md @@ -13,7 +13,7 @@ Each CRD is an object of an API library. In addition to the CRDs documented in this section, Keptn populates many resources on its own. For a comprehensive list of all Keptn resources, see -[API Reference](../crd-ref). +[API Reference](../../crd-ref). For more information about CRDs and APIs, see the Kubernetes documentation: diff --git a/docs/content/en/docs/yaml-crd-ref/analysis.md b/docs/content/en/docs/reference/crd-reference/analysis.md similarity index 97% rename from docs/content/en/docs/yaml-crd-ref/analysis.md rename to docs/content/en/docs/reference/crd-reference/analysis.md index d62871a5bb..f3a61961ea 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysis.md +++ b/docs/content/en/docs/reference/crd-reference/analysis.md @@ -321,12 +321,12 @@ This `Analysis` resource: will be substituted for this string. For a full example of how to implement the Keptn Analysis feature, see the -[Analysis](../implementing/slo.md) +[Analysis](../../guides/slo.md) guide page. ## Files -API reference: [Analysis](../crd-ref/metrics/v1beta1/#analysis) +API reference: [Analysis](../../crd-ref/metrics/v1beta1/_index.md#analysis) ## Differences between versions @@ -347,11 +347,11 @@ To preview these features, do one of the following for your Keptn cluster: file See -[Customizing the configuration of components](../install/install.md#customizing-the-configuration-of-components) +[Customizing the configuration of components](../../installation/_index.md#customizing-the-configuration-of-components) for more information. ## See also * [AnalysisDefinition](analysisdefinition.md) * [AnalysisValueTemplate](analysisvaluetemplate.md) -* [Analysis](../implementing/slo.md) guide +* [Analysis](../../guides/slo.md) guide diff --git a/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md b/docs/content/en/docs/reference/crd-reference/analysisdefinition.md similarity index 97% rename from docs/content/en/docs/yaml-crd-ref/analysisdefinition.md rename to docs/content/en/docs/reference/crd-reference/analysisdefinition.md index 70fb5b8d17..1ace8713ad 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysisdefinition.md +++ b/docs/content/en/docs/reference/crd-reference/analysisdefinition.md @@ -150,13 +150,13 @@ spec: ``` For an example of how to implement the Keptn Analysis feature, see the -[Analysis](../implementing/slo.md) +[Analysis](../../guides/slo.md) guide page. ## Files API reference: -[AnalysisDefinition](../crd-ref/metrics/v1beta1/#analysisdefinition) +[AnalysisDefinition](../../crd-ref/metrics/v1beta1/_index.md#analysisdefinition) ## Differences between versions @@ -170,4 +170,4 @@ reference page for instructions to activate the preview of this feature. * [Analysis](analysis.md) * [AnalysisValueTemplate](analysisvaluetemplate.md) -* [Analysis](../implementing/slo.md) guide +* [Analysis](../../guides/slo.md) guide diff --git a/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md b/docs/content/en/docs/reference/crd-reference/analysisvaluetemplate.md similarity index 92% rename from docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md rename to docs/content/en/docs/reference/crd-reference/analysisvaluetemplate.md index 3e82553b45..4c917f0c53 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysisvaluetemplate.md +++ b/docs/content/en/docs/reference/crd-reference/analysisvaluetemplate.md @@ -33,7 +33,7 @@ spec: * **metadata** * **labels** -- The Analysis feature uses the `name` and `part-of` labels that are discussed in - [Basic annotations](../implementing/integrate.md#basic-annotations) + [Basic annotations](../../guides/integrate.md#basic-annotations) plus the following: * **app.kubernetes.io/instance** analysis-sample * **app.kubernetes.io/managed-by** -- Tool used to manage @@ -88,24 +88,24 @@ The template refers to that provider and queries it. For a full example of how the `AnalysisValueTemplate` is used to implement the Keptn Analysis feature, see the -[Analysis](../implementing/slo.md) +[Analysis](../../guides/slo.md) guide page. ## Files API reference: -[AnalysisValueTemplate](../crd-ref/metrics/v1beta1/#analysisvaluetemplate) +[AnalysisValueTemplate](../../crd-ref/metrics/v1beta1/#analysisvaluetemplate) ## Differences between versions A preliminary release of the Keptn Analysis feature is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. See the -[Analysis](analysis.md/#differences-between-versions) +[Analysis](analysis.md#differences-between-versions) reference page for instructions to activate the preview of this feature. ## See also * [Analysis](analysis.md) * [AnalysisDefinition](analysisdefinition.md) -* [Analysis](../implementing/slo.md) guide +* [Analysis](../../guides/slo.md) guide diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/reference/crd-reference/app.md similarity index 88% rename from docs/content/en/docs/yaml-crd-ref/app.md rename to docs/content/en/docs/reference/crd-reference/app.md index e2b9591a7f..493a514679 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/reference/crd-reference/app.md @@ -1,7 +1,7 @@ --- title: KeptnApp description: Define all workloads and checks associated with an application -weight: 10 +weight: 20 --- A `KeptnApp` resource lists all the [workloads](https://kubernetes.io/docs/concepts/workloads/) @@ -69,7 +69,7 @@ when the app discovery feature generates the `KeptnApp` resource: that failed to deploy, perhaps because a `preDeploymentEvaluation` or `preDeploymentTask` failed. See - [Restart an Application Deployment](../implementing/restart-application-deployment.md) + [Restart an Application Deployment](../../guides/restart-application-deployment.md) for a longer discussion of this. - **workloads** - **name** (required) -- name of this Kubernetes @@ -121,10 +121,10 @@ into the repository of the deployment engine and is then deployed by that deployment engine. A `KeptnApp` resource is created automatically, using the -[automatic application discovery](../implementing/integrate.md#use-keptn-automatic-app-discovery) +[automatic application discovery](../../guides/auto-app-discovery.md) feature to generate a `KeptnApp` resource based on the -[basic annotations](../implementing/integrate.md#basic-annotations) +[basic annotations](../../guides/integrate.md#basic-annotations) that are applied to any of the workload resources. This allows you to use the Keptn observability features for existing resources without manually populating any Keptn related resources. @@ -170,9 +170,9 @@ spec: - [KeptnTaskDefinition](taskdefinition.md) - [KeptnEvaluationDefinition](evaluationdefinition.md) -- [Working with tasks](../implementing/tasks.md) -- [Architecture of KeptnWorkloads and KeptnTasks](../architecture/keptn-apps.md) -- [Pre- and post-deployment tasks](../implementing/integrate.md#pre--and-post-deployment-checks) -- [Orchestrate deployment checks](../intro/usecase-orchestrate.md) -- [Use Keptn automatic app discovery](../implementing/integrate.md#use-keptn-automatic-app-discovery) -- [Restart an Application Deployment](../implementing/restart-application-deployment.md) +- [Working with tasks](../../guides/tasks.md) +- [Architecture of KeptnWorkloads and KeptnTasks](../../components/lifecycle-operator/keptn-apps.md) +- [Pre- and post-deployment tasks](../../guides/integrate.md#pre--and-post-deployment-checks) +- [Orchestrate deployment checks](../../core-concepts/usecase-orchestrate.md) +- [Use Keptn automatic app discovery](../../guides/auto-app-discovery.md) +- [Restart an Application Deployment](../../guides/restart-application-deployment.md) diff --git a/docs/content/en/docs/yaml-crd-ref/config.md b/docs/content/en/docs/reference/crd-reference/config.md similarity index 86% rename from docs/content/en/docs/yaml-crd-ref/config.md rename to docs/content/en/docs/reference/crd-reference/config.md index d5df29c83a..c2a3e9d915 100644 --- a/docs/content/en/docs/yaml-crd-ref/config.md +++ b/docs/content/en/docs/reference/crd-reference/config.md @@ -1,7 +1,7 @@ --- title: KeptnConfig description: Define configuration values -weight: 20 +weight: 10 --- `KeptnConfig` defines Keptn configuration values. @@ -69,12 +69,12 @@ spec: API Reference: -* [KeptnTaskDefinition](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinition) +* [KeptnTaskDefinition](../../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinition) ## Differences between versions ## See also -* [KeptnApp](../yaml-crd-ref/app.md) -* [OpenTelemetry observability](../implementing/otel.md) -* [Keptn automatic app discovery](../implementing/integrate.md/#use-keptn-automatic-app-discovery) +* [KeptnApp](./app.md) +* [OpenTelemetry observability](../../guides/otel.md) +* [Keptn automatic app discovery](../../guides/auto-app-discovery.md) diff --git a/docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md b/docs/content/en/docs/reference/crd-reference/evaluationdefinition.md similarity index 99% rename from docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md rename to docs/content/en/docs/reference/crd-reference/evaluationdefinition.md index 69e0099218..3aab0aa4e0 100644 --- a/docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md +++ b/docs/content/en/docs/reference/crd-reference/evaluationdefinition.md @@ -1,8 +1,7 @@ --- title: KeptnEvaluationDefinition description: Define an evaluation query - -weight: 20 +weight: 50 --- A `KeptnEvaluationDefinition` assigns target values diff --git a/docs/content/en/docs/yaml-crd-ref/metric.md b/docs/content/en/docs/reference/crd-reference/metric.md similarity index 95% rename from docs/content/en/docs/yaml-crd-ref/metric.md rename to docs/content/en/docs/reference/crd-reference/metric.md index 2890a31931..ba98491305 100644 --- a/docs/content/en/docs/yaml-crd-ref/metric.md +++ b/docs/content/en/docs/reference/crd-reference/metric.md @@ -161,6 +161,6 @@ spec: * [KeptnEvaluationDefinition](evaluationdefinition.md) * [KeptnMetricsProvider](metricsprovider.md) -* Implementing [Keptn Metrics](../implementing/evaluatemetrics.md) -* [Getting started with Keptn metrics](../getting-started/metrics.md) -* Architecture of the [Keptn Metrics Operator](../architecture/components/metrics-operator.md) +* Implementing [Keptn Metrics](../../guides/evaluatemetrics.md) +* [Getting started with Keptn metrics](../../getting-started/metrics.md) +* Architecture of the [Keptn Metrics Operator](../../components/metrics-operator/_index.md) diff --git a/docs/content/en/docs/yaml-crd-ref/metricsprovider.md b/docs/content/en/docs/reference/crd-reference/metricsprovider.md similarity index 97% rename from docs/content/en/docs/yaml-crd-ref/metricsprovider.md rename to docs/content/en/docs/reference/crd-reference/metricsprovider.md index 9ecf359576..fd3df7438e 100644 --- a/docs/content/en/docs/yaml-crd-ref/metricsprovider.md +++ b/docs/content/en/docs/reference/crd-reference/metricsprovider.md @@ -107,7 +107,7 @@ spec: API Reference: -* [KeptnEvaluationDefinition](../crd-ref/lifecycle/v1alpha3/_index.md#keptnevaluationdefinition) +* [KeptnEvaluationDefinition](../../crd-ref/lifecycle/) ## Differences between versions diff --git a/docs/content/en/docs/yaml-crd-ref/task.md b/docs/content/en/docs/reference/crd-reference/task.md similarity index 91% rename from docs/content/en/docs/yaml-crd-ref/task.md rename to docs/content/en/docs/reference/crd-reference/task.md index 40618974c0..018b66742c 100644 --- a/docs/content/en/docs/yaml-crd-ref/task.md +++ b/docs/content/en/docs/reference/crd-reference/task.md @@ -1,12 +1,12 @@ --- title: KeptnTask description: Define a run of a KeptnTaskDefinition -weight: 85 +weight: 40 --- Keptn uses KeptnTask resources internally to manage tasks (and their underlying Kubernetes Job resources) -that are run before and after deployment of your workloads +that are run before and after deployment of your workloads (pre- and post-deployment tasks). You do not need to create this resource yourself except in special situations, like using Keptn to manage workloads that are outside of the k8s cluster. @@ -55,7 +55,7 @@ spec: or in the Keptn installation namespace. * **context** (required) -- Contextual information about the task execution * **appName** (required) -- Name of the - [KeptnApp](../yaml-crd-ref/app.md) resource + [KeptnApp](app.md) resource for which the `KeptnTask` is being executed. * **appVersion** (required) -- Version of the `KeptnApp` resource for which the `KeptnTask` is being executed. @@ -85,7 +85,7 @@ spec: * **secureParameters** -- Secure parameters that are passed to the job that executes the `KeptnTask`. These are stored and accessed as Kubernetes `Secrets` in the cluster. - See [Working with secrets](../implementing/tasks.md#working-with-secrets) + See [Working with secrets](../../guides/tasks.md#working-with-secrets) for more information. * **checkType** -- Defines whether task is part of pre- or post-deployment phase. Keptn populates this field based on annotations @@ -117,11 +117,11 @@ so `helloworldtask-1` becomes `helloworldtask-2`, etc. For a full example of how to create a `KeptnTask` resource to use for a deployment being done outside of Kubernetes, see -[Keptn for Non-Kubernetes Applications](../implementing/tasks-non-k8s-apps.md). +[Keptn for Non-Kubernetes Applications](../../use-cases/non-k8s.md). ## Files -[API reference](../crd-ref/lifecycle/v1alpha3/#keptntaskspec) +[API reference](../../crd-ref/lifecycle/v1alpha3/#keptntaskspec) ## Differences between versions @@ -131,4 +131,4 @@ in Keptn v0.8.0. ## See also * [KeptnTaskDefinition](taskdefinition.md) -* [Keptn for Non-Kubernetes Applications](../implementing/tasks-non-k8s-apps.md) +* [Keptn for Non-Kubernetes Applications](../../use-cases/non-k8s.md) diff --git a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md b/docs/content/en/docs/reference/crd-reference/taskdefinition.md similarity index 92% rename from docs/content/en/docs/yaml-crd-ref/taskdefinition.md rename to docs/content/en/docs/reference/crd-reference/taskdefinition.md index 406468eb3b..4dd7039d12 100644 --- a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md +++ b/docs/content/en/docs/reference/crd-reference/taskdefinition.md @@ -1,13 +1,13 @@ --- title: KeptnTaskDefinition description: Define tasks that can be run pre- or post-deployment -weight: 89 +weight: 30 --- A `KeptnTaskDefinition` defines tasks that Keptn runs as part of the pre- and post-deployment phases of a [KeptnApp](./app.md) or -[KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload). +[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/_index.md#keptnworkload). A Keptn task executes as a [runner](https://docs.gitlab.com/runner/executors/kubernetes.html#how-the-runner-creates-kubernetes-pods) @@ -156,7 +156,7 @@ spec: [image concepts](https://kubernetes.io/docs/concepts/containers/images/) and pushed to a registry * **other fields** -- The full list of valid fields is available at - [ContainerSpec](../crd-ref/lifecycle/v1alpha3/#containerspec), + [ContainerSpec](../../crd-ref/lifecycle/v1alpha3/_index.md#containerspec), with additional information in the Kubernetes [Container](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container) spec documentation. @@ -305,7 +305,7 @@ spec: See [Passing secrets, environment variables, and modifying the python command](#passing-secrets-environment-variables-and-modifying-the-python-command) and - [Parameterized functions](../implementing/tasks.md#parameterized-functions) + [Parameterized functions](../../guides/tasks.md#parameterized-functions) for more information. * **deno example:** @@ -321,7 +321,7 @@ spec: Note that, currently, only one secret can be passed per `KeptnTaskDefinition` resource. - See [Create secret text](../implementing/tasks.md#create-secret-text) + See [Create secret text](../../guides/tasks.md#create-secret-text) for details. * **deno example:** @@ -333,7 +333,7 @@ spec: A Task executes the TaskDefinition of a [KeptnApp](app.md) or a -[KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload). +[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/#keptnworkload). The execution is done by spawning a Kubernetes [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) to handle a single Task. @@ -358,7 +358,7 @@ and and in the [KeptnApp](app.md) resource. See -[Pre- and post-deployment tasks](../implementing/integrate.md#pre--and-post-deployment-checks) +[Pre- and post-deployment tasks](../../guides/integrate.md#pre--and-post-deployment-checks) for details. Note that the annotation identifies the task by `name`. This means that you can modify the `function` code in the resource definition @@ -371,7 +371,7 @@ either by using the `inline` syntax for a pre-defined container image or by creating your own image and running it in the Keptn `container-runtime` runner. See -[Executing sequential tasks](../implementing/tasks.md#executing-sequential-tasks) +[Executing sequential tasks](../../guides/tasks.md#executing-sequential-tasks) for more information. ## Examples for a container-runtime runner @@ -567,14 +567,14 @@ directory for more example `KeptnTaskDefinition` YAML files. API Reference: -* [KeptnTaskDefinition](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinition) -* [KeptnTaskDefinitionList](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionlist) -* [KeptnTaskDefinitionSpec](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionspec) -* [FunctionReference](../crd-ref/lifecycle/v1alpha3/_index.md#functionreference) -* [FunctionSpec](../crd-ref/lifecycle/v1alpha3/_index.md#runtimespec) -* [FunctionStatus](../crd-ref/lifecycle/v1alpha3/_index.md#functionstatus) -* [HttpReference](../crd-ref/lifecycle/v1alpha3/_index.md#httpreference) -* [Inline](../crd-ref/lifecycle/v1alpha3/_index.md#inline) +* [KeptnTaskDefinition](../../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinition) +* [KeptnTaskDefinitionList](../../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionlist) +* [KeptnTaskDefinitionSpec](../../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionspec) +* [FunctionReference](../../crd-ref/lifecycle/v1alpha3/_index.md#functionreference) +* [FunctionSpec](../../crd-ref/lifecycle/v1alpha3/_index.md#runtimespec) +* [FunctionStatus](../../crd-ref/lifecycle/v1alpha3/_index.md#functionstatus) +* [HttpReference](../../crd-ref/lifecycle/v1alpha3/_index.md#httpreference) +* [Inline](../../crd-ref/lifecycle/v1alpha3/_index.md#inline) ## Differences between versions @@ -608,8 +608,8 @@ This modifies the synopsis in the following ways: ## See also * [KeptnApp](app.md) -* [Working with tasks](../implementing/tasks.md) -* [Pre- and post-deployment tasks](../implementing/integrate.md#pre--and-post-deployment-checks) -* [KeptnApp and KeptnWorkload resources](../architecture/keptn-apps.md). -* [Orchestrate deployment checks](../intro/usecase-orchestrate.md) -* [Executing sequential tasks](../implementing/tasks.md#executing-sequential-tasks) +* [Working with tasks](../../guides/tasks.md) +* [Pre- and post-deployment tasks](../../guides/integrate.md#pre--and-post-deployment-checks) +* [KeptnApp and KeptnWorkload resources](../../components/lifecycle-operator/keptn-apps.md). +* [Orchestrate deployment checks](../../core-concepts/usecase-orchestrate.md) +* [Executing sequential tasks](../../guides/tasks.md#executing-sequential-tasks) diff --git a/docs/content/en/docs/snippets/tasks/k8s_version_output.md b/docs/content/en/docs/snippets/tasks/k8s_version_output.md deleted file mode 100644 index eea156d127..0000000000 --- a/docs/content/en/docs/snippets/tasks/k8s_version_output.md +++ /dev/null @@ -1,9 +0,0 @@ - -```shell -$ kubectl version --short -Flag --short has been deprecated, and will be removed in the future. The --short output will become the default. -Client Version: v1.24.0 -Kustomize Version: v4.5.4 -Server Version: v1.24.0 -``` - diff --git a/docs/content/en/docs/use-cases/_index.md b/docs/content/en/docs/use-cases/_index.md new file mode 100644 index 0000000000..37ac29a6c9 --- /dev/null +++ b/docs/content/en/docs/use-cases/_index.md @@ -0,0 +1,6 @@ +--- +title: Use Cases +description: +weight: 40 +--- + diff --git a/docs/content/en/docs/implementing/day-2-operations.md b/docs/content/en/docs/use-cases/day-2-operations.md similarity index 90% rename from docs/content/en/docs/implementing/day-2-operations.md rename to docs/content/en/docs/use-cases/day-2-operations.md index df92e2e4ec..ba27e52cac 100644 --- a/docs/content/en/docs/implementing/day-2-operations.md +++ b/docs/content/en/docs/use-cases/day-2-operations.md @@ -1,11 +1,11 @@ --- -title: Day 2 Operations with Keptn +title: Day 2 Operations description: How to operate and maintain your Keptn Apps -weight: 500 +weight: 10 --- After you have successfully rolled out your application by following -the instructions in the [integration guide](./integrate.md), +the instructions in the [integration guide](../guides/integrate.md), Keptn also assists you with day 2 operations for your application. Tasks that fall under this category include: @@ -13,11 +13,11 @@ Tasks that fall under this category include: * Updating the version of one or more [workloads](https://kubernetes.io/docs/concepts/workloads/) that are part of the same application * Adding a new [workload](https://kubernetes.io/docs/concepts/workloads/) to an existing application -* Monitoring the health of your application using `KeptnMetrics`, as described [here](./evaluatemetrics.md) +* Monitoring the health of your application using `KeptnMetrics`, as described [here](../guides/evaluatemetrics.md) * Optimizing the resource usage of your applications by integrating `KeptnMetrics` into a [HorizontalPodAutoscaler (HPA)](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/), -as described [here](./evaluatemetrics.md/#using-the-horizontalpodautoscaler) +as described [here](./hpa.md) ## Updating Workload Versions @@ -46,7 +46,7 @@ let's assume the following example, including a [workload](https://kubernetes.io/docs/concepts/workloads/) called `podtato-head-frontend` that includes a pre-task and a pre-evaluation. -{{< docsembed path="content/en/docs/implementing/assets/deployment-initial.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/deployment-initial.yaml" >}} Now, let's assume that the configuration of that [workload](https://kubernetes.io/docs/concepts/workloads/) needs to be changed. In this example we assume that the image of that [workload](https://kubernetes.io/docs/concepts/workloads/) @@ -59,7 +59,7 @@ of the result of any task or evaluation, e.g., when the previously used image ha and the image must be updated as quickly as possible. To do that, change `podtato-head-frontend` as follows: -{{< docsembed path="content/en/docs/implementing/assets/deployment-new-image.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/deployment-new-image.yaml" >}} * **Update the configuration *and* the version label:** Doing so causes the `KeptnWorkload` that is associated @@ -68,7 +68,7 @@ and therefore the pre-task `my-task` and pre-evaluation `my-evaluation` are executed before the updated pods are scheduled. In this case, the deployment should be changed as follows: -{{< docsembed path="content/en/docs/implementing/assets/deployment-new-image-and-version.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/deployment-new-image-and-version.yaml" >}} If you have defined the related `KeptnApp` resource yourself, this must also be updated to refer to the updated `KeptnWorkload`. @@ -77,14 +77,14 @@ this updated deployment is not able to progress otherwise. Therefore, make sure that the version of `podtato-head-frontend` is updated accordingly: -{{< docsembed path="content/en/docs/implementing/assets/app-updated-version.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/app-updated-version.yaml" >}} Updating the `KeptnApp` also causes all pre-/post-tasks/evaluations of the `KeptnApp` to be executed again. In this example, this means that the tasks `wait-for-prometheus`, and `post-deployment-loadtests` will run again. -If you are using the [automatic app discovery](./integrate.md#use-keptn-automatic-app-discovery), +If you are using the [automatic app discovery](../guides/auto-app-discovery.md), you do not need to update the `KeptnApp` resource. Keptn will take care of that for you. @@ -133,7 +133,7 @@ For example, to add the deployment `podtato-head-left-leg` to the `podtato-head` application, the configuration for that new deployment would look like this, with the required label being set: -{{< docsembed path="content/en/docs/implementing/assets/new-deployment.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/new-deployment.yaml" >}} The `KeptnApp`, if defined by the user, should contain the reference to the newly added [workload](https://kubernetes.io/docs/concepts/workloads/). @@ -142,7 +142,7 @@ progress if it is not part of a `KeptnApp`. For automatically discovered apps this is done automatically. -{{< docsembed path="content/en/docs/implementing/assets/app-with-new-workload.yaml" >}} +{{< docsembed path="content/en/docs/guides/assets/app-with-new-workload.yaml" >}} After applying the updated manifests, you can monitor the status of the application and related [workloads](https://kubernetes.io/docs/concepts/workloads/) using the following commands: diff --git a/docs/content/en/docs/use-cases/hpa.md b/docs/content/en/docs/use-cases/hpa.md new file mode 100644 index 0000000000..c9fb2fd56e --- /dev/null +++ b/docs/content/en/docs/use-cases/hpa.md @@ -0,0 +1,44 @@ +--- +title: Keptn + HorizontalPodAutoscaler +description: Using the HorizontalPodAutoscaler +weight: 20 +--- + +Use the Kubernetes Custom Metrics API +to refer to `KeptnMetric` via the +[Kubernetes HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) +(HPA), +as in the following example: + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: podtato-head-entry + namespace: podtato-kubectl +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: podtato-head-entry + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Object + object: + metric: + name: keptnmetric-sample + describedObject: + apiVersion: metrics.keptn.sh/v1beta1 + kind: KeptnMetric + name: keptnmetric-sample + target: + type: Value + value: "10" +``` + +See the +[Scaling Kubernetes Workloads based on Dynatrace Metrics](https://www.linkedin.com/pulse/scaling-kubernetes-workloads-based-dynatrace-metrics-keptnproject/) +blog post +for a detailed discussion of doing this with Dynatrace metrics. +The same approach could be used to implement HPA with other data providers. diff --git a/docs/content/en/docs/implementing/tasks-non-k8s-apps.md b/docs/content/en/docs/use-cases/non-k8s.md similarity index 89% rename from docs/content/en/docs/implementing/tasks-non-k8s-apps.md rename to docs/content/en/docs/use-cases/non-k8s.md index e06087ad0e..2b57d34a4c 100644 --- a/docs/content/en/docs/implementing/tasks-non-k8s-apps.md +++ b/docs/content/en/docs/use-cases/non-k8s.md @@ -1,9 +1,10 @@ --- -title: Keptn for Non-Kubernetes Applications +title: Keptn - Kubernetes description: Using Keptn with Non-Kubernetes Applications -weight: 95 +weight: 30 --- + Keptn Tasks running on a Kubernetes cluster can be triggered for [workloads](https://kubernetes.io/docs/concepts/workloads/) and applications that are deployed outside of Kubernetes. @@ -20,10 +21,10 @@ To do this: ## Install Keptn on a Kubernetes cluster You must set up a Kubernetes cluster and -[install](../install/install.md/#basic-installation) +[install](../installation/_index.md#basic-installation) Keptn on it, but this can be a very lightweight, single-node KinD cluster; see -[Create local Kubernetes cluster](../install/k8s.md/#create-local-kubernetes-cluster). +[Create local Kubernetes cluster](../installation/k8s.md#create-local-kubernetes-cluster). Keptn only triggers on-demand `KeptnTask` resources so resource utilization is minimal. @@ -33,9 +34,9 @@ When you have Keptn installed, create a YAML file that defines what you want to execute as a `KeptnTaskDefinition` resource. See -[Deployment tasks](./tasks.md) +[Deployment tasks](../guides/tasks.md) and the -[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md/) +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) reference page for more information. For example, you might create a `test-task-definition.yaml` file @@ -59,13 +60,13 @@ spec: This example uses the `container-runtime` runner, but you can instead use the `deno-runtime` or `python-runtime` runner. See -[Runners and containers](./tasks.md#runners-and-containers) +[Runners and containers](../guides/tasks.md#runners-and-containers) for more information. ## Create and apply a KeptnTask You must manually create the -[KeptnTask](../yaml-crd-ref/task.md) resource. +[KeptnTask](../reference/crd-reference/task.md) resource. In the standard operating mode, when Keptn is managing [workloads](https://kubernetes.io/docs/concepts/workloads/), the creation of the `KeptnTask` resource is automatic. diff --git a/docs/layouts/shortcodes/embed.html b/docs/layouts/shortcodes/embed.html index fc87a3f634..9d7c2325c3 100644 --- a/docs/layouts/shortcodes/embed.html +++ b/docs/layouts/shortcodes/embed.html @@ -7,5 +7,5 @@ {{- highlight (.Content | htmlUnescape | safeHTML ) "yaml" -}} {{ end }} {{ else }} - {{ errorf "Unable to get remote resource." }} + {{ errorf "Unable to get remote resource: %s" $u }} {{ end }} diff --git a/examples/support/observability/README.md b/examples/support/observability/README.md index 947a3e7f5d..cd719c8071 100644 --- a/examples/support/observability/README.md +++ b/examples/support/observability/README.md @@ -22,7 +22,7 @@ based on prometheus metrics. For information about installing and configuring the software required, see -[OpenTelemetry observability](../../../docs/content/en/docs/implementing/otel.md/) +[OpenTelemetry observability](../../../docs/content/en/docs/guides/otel.md) in the documentation. ## Seeing the OpenTelemetry Collector in action