From 087b60f0916c8a94830b81cdea3c4cd4a217572e Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 10 Aug 2023 01:00:27 -0700 Subject: [PATCH 1/3] docs: improve how-to and ref info for apps Signed-off-by: Meg McRoberts --- .../architecture/keptn-apps/_index.md | 127 ++++++ .../getting-started/observability/_index.md | 25 +- .../getting-started/orchestrate/_index.md | 23 +- .../en/docs/implementing/integrate/_index.md | 380 +++++++++++------- docs/content/en/docs/install/_index.md | 18 +- docs/content/en/docs/install/install.md | 4 + docs/content/en/docs/yaml-crd-ref/app.md | 46 ++- .../en/docs/yaml-crd-ref/taskdefinition.md | 1 + 8 files changed, 419 insertions(+), 205 deletions(-) create mode 100644 docs/content/en/docs/concepts/architecture/keptn-apps/_index.md diff --git a/docs/content/en/docs/concepts/architecture/keptn-apps/_index.md b/docs/content/en/docs/concepts/architecture/keptn-apps/_index.md new file mode 100644 index 0000000000..ac9dfa2e37 --- /dev/null +++ b/docs/content/en/docs/concepts/architecture/keptn-apps/_index.md @@ -0,0 +1,127 @@ +--- +title: KeptnApp and KeptnWorkload resources +linktitle: Keptn Applications and Keptn Workloads +description: How Keptn applications work +weight: 50 +cascade: +--- + +## Keptn Workloads + +A +[KeptnWorkload](../../../crd-ref/lifecycle/v1alpha3/#keptnworkload) +resource augments a Kubernetes +[Workload](https://kubernetes.io/docs/concepts/workloads/) +with the ability to handle extra phases. +It can execute the pre- and post-deployment evaluations of a Workload +and run pre- and post-deployment tasks. + +In its state, it tracks the currently active `Workload Instances`, +(`Pod`, `DaemonSet`, `StatefulSet`, and `ReplicaSet` resources), +as well as the overall state of the Pre Deployment phase, +which the scheduler can use to determine +whether the pods belonging to a workload +should be created and assigned to a node. +When it detects that the referenced object has reached its desired state +(e.g. all pods of a deployment are up and running), +it knows that a`PostDeploymentCheck` can be triggered. + +The `KeptnWorkload` resources are created automatically +and without delay by the mutating webhook +as soon as the workload manifest is applied. + +## Keptn Applications + +A [KeptnApp](../../../yaml-crd-ref/app.md) +resource combines multiple Kubernetes +[workloads](https://kubernetes.io/docs/concepts/workloads/) +into a single entity +that represent the application that is published. +Note that the Kubernetes documentation +often refers to workloads as applications, +but each workload actually corresponds to one version +of one deployable microservice, +not the amalgamation of multiple microservices +that typically comprise the released software. + +Implementing Keptn applications provides the following benefits: + +* Observability tools report on the deployment + of all workloads together rather than individually. +* You can define pre-deployment evaluations and tasks + that must all complete successfully + before the scheduler creates the pods for any of the workloads. +* You can define post-deployment evaluations and tasks + that run only after all the workloads have completed successfully. + +You control the content of a `KeptnApp` resource +with annotations or labels that are applied to each +[Workload](https://kubernetes.io/docs/concepts/workloads/) +([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +and +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) +plus specific tasks and evaluations that you define +for the `KeptnApp` resource itself: + +* The annotations described in + [Basic annotations](../../../implementing/integrate/#basic-annotations) + are used to automatically generate `KeptnApp` resources + that contain the identifications required + to run the KLT observability features. +* You must manually add the annotations described in + [Pre- and post-deployment checks](../../../implementing/integrate/#pre--and-post-deployment-checks) + to the basic `KeptnApp` manifest to define + the evaluations and tasks you want to run pre- and post-deployment. + +The `KeptnApp` resources that are generated automatically +contain the identifications required to run the KLT observability features. +The `spec.workloads.name` and a `spec.workloads.version` fields +that define evaluations and tasks to be run +pre- and post-deployment are not generated automatically +but must be input manually. + +By default, the `KeptnApp` resources are updated every 30 seconds +when any of the Workloads have been modified; +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) +resource. + +## How basic annotations are implemented + +The [Basic annotations](../../../implementing/integrate/#basic-annotations) +page gives instructions for applying the annotations or labels +that identify the pods that KLT should manage. + +Three `keptn.sh` and three `app.kubernetes.io` keys are recognized. +They are equivalent; you can use either of them +and they can be implemented as either annotations or labels. +Annotations take precedence over labels, +and the `keptn.sh` keys take precedence over `app.kubernetes.io` keys. +In other words: + +* The operator first checks if the `keptn.sh/` key is present + in the annotations, and then in the labels. +* If neither is the case, it looks for the `app.kubernetes.io/` equivalent, + again first in the annotations, then in the labels. + +KLT automatically generates appropriate +[KeptnApp](../../../yaml-crd-ref/app.md) +resources that are used for observability, +based on whether the `keptn.sh/app` or `app.kubernetes.io/part-of` +annotation/label is poulated: +resource for each defined group. +that together constitute a single deployable Keptn Application. + +* If either of these labels/allotations are populated, + KLT automatically generates a `KeptnApp` resource + that includes all workloads that have the same annotation/label, + thus creating a `KeptnApp` resource for each defined grouping + +* If only the `workload` and `version` annotations/labels are available + (in other words, neither the `keptn.sh/app` + or `app.kubernetes.io/part-of` annotation/label is populated), + one `KeptnApp` resource is created automatically for each workload. diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index ab27d7deca..24b8e4de08 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -70,23 +70,14 @@ you need to do the following: [Install and update](../../install) to install and enable KLT on your cluster. 1. Follow the instructions in - [Integrate KLT with your applications](../../implementing/integrate) - to integrate KLT with your Kubernetes cluster. - This requires the following: - - - Follow the instructions in - [Annotate workload](../../implementing/integrate/#basic-annotations) - to integrate the Lifecycle Toolkit into your Kubernetes cluster - by applying basic annotations - to your workload and pod resources. - - Follow the instructions in - [Define a Keptn application](../../implementing/integrate/#define-a-keptn-application) - to create a Keptn application that aggragates - all the `workloads` for your deployment into a single - [KeptnApp](../../yaml-crd-ref/app.md) resource. - For this exercise, we recommend that you use - [Keptn automatic app discovery](../../implementing/integrate/#use-keptn-automatic-app-discovery) - to automatically generate a Keptn Application. + [Basic annotations](../../implementing/integrate/#basic-annotations) + to integrate the Lifecycle Toolkit into your Kubernetes cluster + by applying basic annotations + to your workload and pod resources. + and to create appropriate + [KeptnApp](../../yaml-crd-ref/app.md) + resources that aggragate + all the `workloads` for a logical deployment into a single resource. ## DORA metrics diff --git a/docs/content/en/docs/getting-started/orchestrate/_index.md b/docs/content/en/docs/getting-started/orchestrate/_index.md index 5251b43ee9..78556d8a6c 100644 --- a/docs/content/en/docs/getting-started/orchestrate/_index.md +++ b/docs/content/en/docs/getting-started/orchestrate/_index.md @@ -77,22 +77,13 @@ you need to do the following: [Install and update](../../install) to install and enable KLT on your cluster. 1. Follow the instructions in - [Integrate KLT with your applications](../../implementing/integrate) - to integrate KLT with your Kubernetes cluster: - - * Follow the instructions in - [Annotate workload](../../implementing/integrate/#basic-annotations) - to integrate the Lifecycle Toolkit into your Kubernetes cluster - by applying basic annotations to your `Deployment` resource. - * Follow the instructions in - [Define a Keptn application](../../implementing/integrate/#define-a-keptn-application) - to create a - [KeptnApp](../../yaml-crd-ref/app.md) resource - that includes all workloads on the cluster, - regardless of the tools being used. - For this exercise, we recommend that you - [Use Keptn automatic app discovery](../../implementing/integrate/#use-keptn-automatic-app-discovery) - to automatically generate a Keptn Application. + [Annotate workload](../../implementing/integrate/#basic-annotations) + to integrate the Lifecycle Toolkit into your Kubernetes cluster + by applying basic annotations to your `Deployment` resource. + This also creates appropriate + [KeptnApp](../../yaml-crd-ref/app.md) resources + which aggregate workloads that are combined into the released product, + regardless of the tools being used. ## Define evaluations to be performed pre- and post-deployment diff --git a/docs/content/en/docs/implementing/integrate/_index.md b/docs/content/en/docs/implementing/integrate/_index.md index 0144d51887..03ffb3ba48 100644 --- a/docs/content/en/docs/implementing/integrate/_index.md +++ b/docs/content/en/docs/implementing/integrate/_index.md @@ -17,165 +17,249 @@ KLT monitors resources that have been applied into the Kubernetes cluster and reacts if it finds a workload with special annotations/labels. The Keptn Lifecycle Toolkit uses metadata +that is added to the Kubernetes workloads to identify the workloads of interest. -To integrate KLT with your applications, -you need to populate the metadata it needs -with either Keptn or Kubernetes annotations and labels. +To integrate KLT with your applications: -This requires two steps: - -* [Annotate your workload(s)](#annotate-workloads) -* Define a Keptn application that references those workloads. - You have two options: +* You must first +[install](../../install/install.md) +and +[enable](../../install/install.md//#enable-klt-for-your-cluster) +KLT. +* Annotate or label your workloads +with either Keptn or Kubernetes keys. + * [Basic annotations](#basic-annotations) + or labels + are required for all KLT features except Keptn metrics. + * [Pre- and post-deployment checks](#basic-annotations) + are required only for the Release lifecycle management feature. + +KLT uses these annotations to the Kubernetes workloads to create the +[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/#keptnworkload) +and +[KeptnApp](../../yaml-crd-ref/app.md) +resources that it uses to provide observability +and release lifecycle management. - * [Define KeptnApp manually](#define-keptnapp-manually) - for the application - * [Use the Keptn automatic app discovery capability](#use-keptn-automatic-app-discovery) - that enables the observability features provided by the Lifecycle Toolkit - for existing applications, - without requiring you to manually create any KeptnApp resources. +> Note: Annotations are not required if you are only using the + `metrics-operator` component of KLT + to observe Keptn metrics. -## Annotate workload(s) +## Basic annotations -To annotate your -[Workload](https://kubernetes.io/docs/concepts/workloads/), -you need to set annotations in your Kubernetes -[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resource. +The Keptn Lifecycle Toolkit automatically discovers `KeptnApp` resources, +based on the annotations or labels. +This enables the KLT observability features +(based on OpenTelemetry) for existing applications, +without additional Keptn configuration. -Note that you do not need to explicitly create a `KeptnWorkload`. -KLT monitors your `Deployments`, +KLT monitors your +[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), and [ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), and [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) -in the namespaces where KLT is enabled. +resources in the namespaces where KLT is enabled. If KLT finds any of these resources and the resource has either -the keptn.sh or the kubernetes recommended labels, -it creates a `KeptnWorkload` resource for the version it detects. - -> Note: Annotations are not required if you are only using the - `metrics-operator` component of KLT - to observe Keptn metrics. - -### Basic annotations +the `keptn.sh` or the `kubernetes` annotations/labels, +it creates appropriate +[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/#keptnworkload) +and +[KeptnApp](../../yaml-crd-ref/app.md) +resources for the version it detects. -The basic keptn.sh annotations are: +The basic keptn.sh keys that can be used for annotations or labels are: ```yaml -keptn.sh/app: myAwesomeAppName keptn.sh/workload: myAwesomeWorkload keptn.sh/version: myAwesomeWorkloadVersion +keptn.sh/app: myAwesomeAppName ``` -Alternatively, you can use Kubernetes -[Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/) -to annotate your workload: +Alternatively, you can use Kubernete keys for annotations or labels. +These are part of the Kubernetes +[Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/): ```yaml -app.kubernetes.io/part-of: myAwesomeAppName app.kubernetes.io/name: myAwesomeWorkload app.kubernetes.io/version: myAwesomeWorkloadVersion +app.kubernetes.io/part-of: myAwesomeAppName ``` -Note the following: +These keys are defined as: -* The Keptn Annotations/Labels take precedence - over the Kubernetes recommended labels. -* If the Workload has no version annotation/labels +* `keptn.sh/workload` or `app.kubernetes.io/name`: Determines the name + of the generated + [KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/#keptnworkload) + resource. +* `keptn.sh/version` or `app.kubernetes.io/version`: + Determines the version of the `KeptnWorkload` + that represents the Workload. + If the Workload has no `version` annotation/labels and the pod has only one container, the Lifecycle Toolkit takes the image tag as version - (if it is not "latest"). - -This process is demonstrated in the -[Keptn Lifecycle Toolkit: Installation and KeptnTask Creation in Mintes](https://www.youtube.com/watch?v=Hh01bBwZ_qM) -video. + (unless it is "latest"). +* `keptn.sh/app` or `app.kubernetes.io/part-of`: Determines the name + of the generated `KeptnApp` representing your Application. + All Workloads that share the same value for this label + are consolidated into the same `KeptnApp` resource. -### Pre- and post-deployment checks - -Further annotations are necessary -to run pre- and post-deployment checks: +KLT automatically generates appropriate +[KeptnApp](../../yaml-crd-ref/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: + +* If either of these annotations/labels are populated, + KLT automatically generates a `KeptnApp` resource + that includes all workloads that have the same annotation/label, + thus creating a `KeptnApp` resource for each defined grouping + +* If only the `workload` and `version` annotations/labels are available + (in other words, neither the `keptn.sh/app` + or `app.kubernetes.io/part-of` annotation/label is populated), + KLT creates a `KeptnApp` resource for each `KeptnWorkload` + and your observability output traces the individual `Keptnworkload` resources + but not the combined workloads that constitute your deployed application. + +See +[Keptn Applications and Keptn Workloads](../../concepts/architecture/keptn-apps/) +for architectural information about how `KeptnApp` and `KeptnWorkloads` +are implemented. + +## Annotations vs. labels + +The same keys can be used as +[annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) +or +[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). +Both annotations and labels are can be attached to Kubernetes objects. +Some key differences between the two: + +* Annotations + * Are not used to identify and select objects + * Can contain up to 262144 chars + * Metadata in an annotation can be small or large, + structured or unstructured, + and can include characters not permitted by labels + +* Labels + * Can be used to select objects + and to find collections of objects that satisfy certain conditions + * Can contain up to 63 chars + * Are appropriate for identifying attributes of objects + that are meaningful and relevant to users + but do not directly imply semantics to the core system + +Annotations take precedence over labels, +and the `keptn.sh` keys take precedence over `app.kubernetes.io` keys. +In other words: + +* The operator first checks if the `keptn.sh` key is present + in the annotations, and then in the labels. +* If neither is the case, it looks for the `app.kubernetes.io` equivalent, + again first in the annotations, then in the labels. + +In general, annotations are more appropriate than labels +for integrating KLT with your applications +because they store references, names, and version information +so the 63 char limitation is quite restrictive. +However labels can be used if you specifically need them +and can accomodate the size restriction. + +## Pre- and post-deployment checks + +To implement the Keptn Release Lifecycle feature +that handles pre- and post-deployment evaluations and tasks, +do the following: + +* Define the + [KeptnMetric](../../yaml-crd-ref/metric.md) + and + [KeptnEvaluationDefinition](../../yaml-crd-ref/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) + and + resource for each instance of each data source + used for the `KeptnEvaluationDefinition` resources you define. +* Define a + [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) + resource for each task you want to execute. + `KeptnTaskDefinition` resources contain re-usable "functions" + that can execute before and after the deployment. + For example, before the deployment starts, + you might run a check for open problems in your infrastructure + and invoke a pipeline to run performance tests. + The deployment is kept in a pending state + until the infrastructure is capable of accepting deployments again. + See + [Working with Keptn tasks](../tasks) + for more information. +* Annotate your [Workloads](https://kubernetes.io/docs/concepts/workloads/) + ([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), + [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), + and + [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) + to include each evaluation and task you want run + for specific workloads. +* Manually edit all + [KeptnApp](../../yaml-crd-ref/app.md) resources + to specify evaluations and tasks to be run for the `KeptnApp` itself. + +### Annotations to KeptnApp + +The annotations to workloads do not define the tasks and evaluations +to be run for `KeptnApp` resources themselves. +To define pre- and post-deployment evaluations and tasks for a `KeptnApp`, +you must manually edit the YAML file to add them. + +Specify one of the following annotations/labels +for each evaluation or task you want to execute: ```yaml -keptn.sh/pre-deployment-tasks: verify-infrastructure-problems -keptn.sh/post-deployment-tasks: slack-notification,performance-test +keptn.sh/pre-deployment-evaluations: <`EvaluationDefinition`-name> +keptn.sh/pre-deployment-tasks: <`TaskDefinition`-name> +keptn.sh/post-deployment-evaluations: <`EvaluationDefinition`-name> +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)s. +[KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) +resources These resources contain re-usable "functions" that can execute before and after the deployment. For example, before the deployment starts, -you might perform a check for open problems in your infrastructure. -If everything is fine, the deployment continues and afterward, -a slack notification can be sent with the result of the deployment -and a pipeline to run performance tests can be invoked. -Otherwise, the deployment is kept in a pending state +you might run a check for open problems in your infrastructure +and invoke a pipeline to run performance tests. +The deployment is kept in a pending state until the infrastructure is capable of accepting deployments again. -A comprehensive example can be found in our -[examples folder](https://github.com/keptn/lifecycle-toolkit/tree/main/examples/sample-app), -where we use [Podtato-Head](https://github.com/podtato-head/podtato-head) -to run some simple pre-deployment checks. +If everything is fine, the deployment continues and afterward, +a slack notification is sent with the result of the deployment -To run the example, use the following commands: +## Use Keptn automatic app discovery -```shell -cd ./examples/podtatohead-deployment/ -kubectl apply -f . -``` +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 KLT observability features on your cluster. Afterward, you can monitor the status of the deployment using +a command like the following: ```shell kubectl get keptnworkloadinstance -n podtato-kubectl -w ``` -The deployment for a Workload stays in a `Pending` -state until the respective pre-deployment check is successfully completed. -Afterwards, the deployment starts and when the workload is deployed, -the post-deployment checks start. - -## Define a Keptn application - -A Keptn application defines the workloads -to be included in your Keptn Application. -It does this by aggregating multiple workloads -that belong to a logical app into a single -[KeptnApp](../../yaml-crd-ref/app.md) -resource. - - You have two options: - -* Create a [KeptnApp](../../yaml-crd-ref/app.md) resource - that references the workloads that should be included - along with any - [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) - and [KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md) - resources that you want -* Use the Keptn automatic app discovery capability - that enables the observability features provided by the Lifecycle Toolkit - for existing applications, - without requiring you to manually create any KeptnApp resources - -### Define KeptnApp manually - -You can manually create a YAML file for the -[KeptnApp](../../yaml-crd-ref/app.md) resource -that references the workloads to be included -along with any -[KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) -and [KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md) -resources that you want. - -See the -[keptn-app.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-app.yaml.tmp) -file for an example. -You see the `metadata` that names this `KeptnApp` -and identifies the namespace where it lives: +The generated `KeptnApp` file includes `metadata` +that names this `KeptnApp` and identifies the Namespace where it resides. ```yaml metadata: @@ -183,49 +267,21 @@ metadata: namespace: simplenode-dev ``` -You can also see the `spec.workloads` list -that defines the workloads to be included -and any pre-/post-deployment -tasks and evaluations to be performed. -In this simple example, -we only have one workload and one evaluation defined -but most production apps will have multiple workloads, -multiple tasks, and multiple evaluations defined. - -### Use Keptn automatic app discovery - -The Keptn Lifecycle Toolkit provides the option -to automatically discover `KeptnApp`s, -based on the recommended Kubernetes labels `app.kubernetes.io/part-of`, -`app.kubernetes.io/name` `app.kubernetes.io/version`. -Because of the OpenTelemetry tracing features -provided by the Keptn Lifecycle Toolkit, -this enables the observability features for existing applications, -without creating any Keptn-related custom resources. - -To enable the automatic discovery of `KeptnApp`s for your existing applications, -the following steps are required: - -1. Enable KLT for the namespace where your application runs - following the instructions above -1. Make sure the following Kubernetes labels and/or annotations are present - in the pod template specs of your Workloads - (`Deployments`, `StatefulSets`, `DaemonSets`, and `ReplicaSets`) - within your application: - - * `app.kubernetes.io/name`: Determines the name - of the generated `KeptnWorkload` representing the Workload. - * `app.kubernetes.io/version`: Determines the version - of the `KeptnWorkload` representing the Workload. - * `app.kubernetes.io/part-of`: Determines the name - of the generated `KeptnApp` representing your Application. - - All Workloads that share the same value for this label - are consolidated into the same `KeptnApp`. +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 several deployments, -which is going to be deployed into a KLT-enabled namespace: +consisting of multiple deployments, +which is going to be deployed into a KLT-enabled namespace. +Note that: + +1. KLT 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 @@ -298,3 +354,29 @@ by using the OpenTelemetry tracing features that are provided by the Keptn Lifecycle Toolkit: ![Application deployment trace](assets/trace.png) + +## Example of pre- and post-deployment actions + +A comprehensive example of pre- and post-deployment +evaluations and tasks can be found in our +[examples folder](https://github.com/keptn/lifecycle-toolkit/tree/main/examples/sample-app), +where we use [Podtato-Head](https://github.com/podtato-head/podtato-head) +to run some simple pre-deployment checks. + +To run the example, use the following commands: + +```shell +cd ./examples/podtatohead-deployment/ +kubectl apply -f . +``` + +Afterward, you can monitor the status of the deployment using + +```shell +kubectl get keptnworkloadinstance -n podtato-kubectl -w +``` + +The deployment for a Workload stays in a `Pending` +state until the respective pre-deployment check is successfully completed. +Afterwards, the deployment starts and when the workload is deployed, +the post-deployment checks start. diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md index d2479e57af..4ed07431de 100644 --- a/docs/content/en/docs/install/_index.md +++ b/docs/content/en/docs/install/_index.md @@ -38,17 +38,13 @@ The steps are: - metrics-operator Unless you are only using the customized Keptn metrics feature, -you now need to: - -- Follow the instructions in - [Annotate workload](../implementing/integrate/#basic-annotations) - to integrate the Lifecycle Toolkit into your Kubernetes cluster - by applying basic annotations to your `Deployment` resource. -- Follow the instructions in - [Define a Keptn application](../implementing/integrate/#define-a-keptn-application) - to create a Keptn application that aggragates - all the `workloads` for your deployment into a single - [KeptnApp](../yaml-crd-ref/app.md) resource. +you now need to: follow the instructions in +[Annotate workload](../implementing/integrate/#basic-annotations) +to integrate the Lifecycle Toolkit into your Kubernetes cluster +by applying basic annotations to your `Deployment` resource. +and create appropriate `KeptnApp` resources, +each of which aggregates all `workloads` of your application into a single +[KeptnApp](../yaml-crd-ref/app.md) resource. This section also includes: diff --git a/docs/content/en/docs/install/install.md b/docs/content/en/docs/install/install.md index f021780190..71e336e294 100644 --- a/docs/content/en/docs/install/install.md +++ b/docs/content/en/docs/install/install.md @@ -160,3 +160,7 @@ metadata: You see the annotation line `keptn.sh/lifecycle-toolkit: "enabled"`. This annotation tells the webhook to handle the namespace. + +After enabling KLT for your namespace(s), +you are ready to +[Integrate KLT with your applications](../implementing/integrate). diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/yaml-crd-ref/app.md index da25dd54bc..3e653b01bc 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/yaml-crd-ref/app.md @@ -45,6 +45,9 @@ spec: ## Fields +The first set of fields are created automatically +when the app discovery feature generates the `KeptnApp` resource: + - **apiVersion** -- API version being used. - **kind** -- Resource type. Must be set to `KeptnApp` @@ -78,20 +81,28 @@ spec: Changing this number causes a new execution of checks for this workload only, not the entire application. - - **preDeploymentTasks** -- list each task + +The remaining fields are required only when implementing +the release lifecycle management feature. +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](taskdefinition.md) resource. - - **postDeploymentTasks** -- list each task +- **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](taskdefinition.md) resource. - - **preDeploymentEvaluations** -- list each evaluation to be run + for the associated + [KeptnTaskDefinition](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](evaluationdefinition.md) + for the associated + [KeptnEvaluationDefinition](evaluationdefinition.md) resource. - - **postDeploymentEvaluations** -- list each evaluation to be run +- **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](evaluationdefinition.md) @@ -109,17 +120,26 @@ into the repository of the deployment engine (ArgoCD, Flux, etc) and is then deployed by that deployment engine. -You can create a `KeptnApp` resource as a standard YAML manifest -or you can use the +A `KeptnApp` resource is created automatically, using the [automatic application discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) -feature to automatically generate a `KeptnApp` resource -based on Keptn or [recommended Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/). +feature to generate a `KeptnApp` resource +based on the +[basic annotations](../implementing/integrate/#basic-annotations) +that are applied to any of the workload resources. This allows you to use the KLT observability features for existing resources without manually populating any Keptn related resources. -## Examples +The release lifecycle management feature +allows you to define pre- and post-deployment +evaluations and tasks to be run for the `KeptnApp` as a whole. +These must be added to the `KeptnApp` manifest manually. +Note that all evaluations or tasks for a specific stage +(such as `preDeploymentTasks`) +are executed in parallel. +If you have a series of tasks that should be executed sequentially, +you can code them all into a single `KeptnTaskDefinition`. -### Example +## Example ```yaml apiVersion: lifecycle.keptn.sh/v1alpha3 @@ -149,7 +169,9 @@ spec: ## See also - [KeptnTaskDefinition](taskdefinition.md) +- [KeptnEvaluationDefinition](evaluationdefinition.md) - [Working with tasks](../implementing/tasks) +- [Architecture of KeptnWorkloads and KeptnTasks](../concepts/architecture/keptn-apps/) - [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks) - [Orchestrate deployment checks](../getting-started/orchestrate) - [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) diff --git a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md index 2e6f473b8b..bcec16fbf7 100644 --- a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md +++ b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md @@ -663,4 +663,5 @@ is allowed per `KeptnTaskDefinition`. * [KeptnApp](app.md) * [Working with tasks](../implementing/tasks) * [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks) +* [KeptnApp and KeptnWorkload resources](../concepts/architecture/keptn-apps/). * [Orchestrate deployment checks](../getting-started/orchestrate) From 8a631a358386741124d89d2fe97fca224e39311b Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 10 Aug 2023 01:08:36 -0700 Subject: [PATCH 2/3] xref Signed-off-by: Meg McRoberts --- docs/content/en/docs/implementing/tasks/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/implementing/tasks/_index.md b/docs/content/en/docs/implementing/tasks/_index.md index 515b926000..33514b908c 100644 --- a/docs/content/en/docs/implementing/tasks/_index.md +++ b/docs/content/en/docs/implementing/tasks/_index.md @@ -24,7 +24,7 @@ To implement a Keptn task: - Define a [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) resource that defines the runner to use for the container -- [Annotate your workloads](../integrate/#annotate-workloads) +- [Annotate your workloads](../integrate.md/#annotate-workloads) to integrate your task with Kubernetes - Add your task to the [KeptnApp](../../yaml-crd-ref/app.md) resource that associates your `KeptnTaskDefinition` From 94f38c569b2ec5db4b505a6681930a0c5fc5fc05 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Thu, 10 Aug 2023 01:28:33 -0700 Subject: [PATCH 3/3] xref to basic-annotations Signed-off-by: Meg McRoberts --- docs/content/en/docs/implementing/tasks/_index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/content/en/docs/implementing/tasks/_index.md b/docs/content/en/docs/implementing/tasks/_index.md index 33514b908c..c2a85ab321 100644 --- a/docs/content/en/docs/implementing/tasks/_index.md +++ b/docs/content/en/docs/implementing/tasks/_index.md @@ -24,11 +24,14 @@ To implement a Keptn task: - Define a [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) resource that defines the runner to use for the container -- [Annotate your workloads](../integrate.md/#annotate-workloads) - to integrate your task with Kubernetes +- Apply [basic-annotations](../integrate/#basic-annotations) + to your workloads to integrate your task with Kubernetes - Add your task to the [KeptnApp](../../yaml-crd-ref/app.md) resource that associates your `KeptnTaskDefinition` - with the pre- and post-deployment tasks that should run in it + with the pre- and post-deployment tasks that should run in it; + see + [Pre- and post-deployment tasks and checks](../integrate/#pre--and-post-deployment-checks) + for more information. This page provides information to help you create your tasks: