From 4aa141a069b8b7d25c508ff92309ad460120beb4 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 10 May 2023 14:21:26 -0700 Subject: [PATCH] docs: create KeptnApp reference page (#1391) Signed-off-by: Meg McRoberts Signed-off-by: Meg McRoberts Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Co-authored-by: Florian Bacher --- docs/content/en/docs/concepts/apps/_index.md | 127 ------------------ docs/content/en/docs/yaml-crd-ref/app.md | 134 +++++++++++++++++++ 2 files changed, 134 insertions(+), 127 deletions(-) delete mode 100644 docs/content/en/docs/concepts/apps/_index.md diff --git a/docs/content/en/docs/concepts/apps/_index.md b/docs/content/en/docs/concepts/apps/_index.md deleted file mode 100644 index 6a058b22b8..0000000000 --- a/docs/content/en/docs/concepts/apps/_index.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Apps -description: Learn what Keptn Apps are and how to use them -icon: concepts -layout: quickstart -weight: 10 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - -An App contains information about all workloads and checks associated with an application. -It will use the following structure for the specification of the pre/post deployment and pre/post evaluations checks -that should be executed at app level: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnApp -metadata: - name: podtato-head - namespace: podtato-kubectl -spec: - version: "1.3" - workloads: - - name: podtato-head-left-arm - version: 0.1.0 - - name: podtato-head-left-leg - version: 1.2.3 - postDeploymentTasks: - - post-deployment-hello - preDeploymentEvaluations: - - my-prometheus-definition -``` - -While changes in the workload version will affect only workload checks, a change in the app version will also cause a -new execution of app level checks. - -## Automatic App Discovery - -The Keptn Lifecycle Toolkit also 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`. -This allows users to enable the observability features provided by the Lifecycle Toolkit for -their existing applications, without the need for creating any Keptn-related custom resources. - -To enable the automatic discovery of `KeptnApp`s for your existing applications, the following steps will -be required: - -1. Make sure the namespace of your application is enabled to be managed by the Keptn Lifecycle Toolkit, -by adding the annotation `keptn.sh/lifecycle-toolkit: "enabled"` to your namespace. -2. Make sure the following labels and/or annotations are present in the pod template -specs of your Workloads (i.e. `Deployments`/`StatefulSets`/`DaemonSets`/`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 will be consolidated into the same `KeptnApp`. - -As an example, consider the following application, consisting of several deployments, which is going to be -deployed into a KLT-enabled namespace: - -```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 will then result in the creation of the following `KeptnApp`: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnApp -metadata: - name: podtato-head - namespace: podtato-kubectl - annotations: - app.kubernetes.io/managed-by: "klt" -spec: - version: "" - workloads: - - name: podtato-head-frontend - version: 0.1.0 - - name: podtato-head-hat - version: 1.1.1 -``` - -Due to the creation of this resource, you will now get observability of your application's deployments due to -the OpenTelemetry tracing features provided by the Keptn Lifecycle Toolkit: - -![Application deployment trace](assets/trace.png) diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/yaml-crd-ref/app.md index 38644caec7..e4d0d790d0 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/yaml-crd-ref/app.md @@ -3,3 +3,137 @@ title: KeptnApp description: Define all workloads and checks associated with an application weight: 10 --- + +`KeptnApp` defines a list of workloads +that together constitute a logical application. +It contains information about all workloads and checks +that are associated with a Keptn application +and a list of tasks and evaluations to be executed +pre- and post-deployment. + +## Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnApp +metadata: + name: + namespace: +spec: + version: "x.y" + revision: x + workloads: + - name: + version: x.y.z + - name: + version: x.y.z + preDeploymentTasks: + - + postDeploymentTasks: + - + preDeploymentEvaluations: + - + postDeploymentEvaluations: + - +``` + +## Fields + +* **apiVersion** -- API version being used. +* **kind** -- Resource type. + Must be set to `KeptnApp` + +* **metadata** + * **name** -- Unique name of this application. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + +* **spec** + * **version** -- version of the Keptn application. + Changing this version number causes a new execution + of all application-level checks + * **revision** -- revision of a `version`. + The value is an integer that can be modified + to trigger another deployment of a `KeptnApp` of the same version. + For example, increment this number to restart a `KeptnApp` version + that failed to deploy, perhaps because a + `preDeploymentEvaluation` or `preDeploymentTask` failed. + * **workloads** + * **name** - name of this Kubernetes + [workload](https://kubernetes.io/docs/concepts/workloads/). + Use the same naming rules listed above for the application name. + Provide one entry for each workload + associated with this Keptn application. + * **version** -- version number for this workload. + Changing this number causes a new execution + of checks for the Keptn application and the new version of the workload. + * **preDeploymentTasks** -- list each task to be run + as part of the pre-deployment stage. + Task names must match the value of the `name` field + for the associated [KeptnTaskDefinition](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 `name` field + 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 `name` field + for the associated [KeptnEvaluationDefinition](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 `name` field + for the associated [KeptnEvaluationDefinition](evaluationdefinition.md) + resource. + +## Usage + +Kubernetes defines +[workloads](https://kubernetes.io/docs/concepts/workloads/) +but does not define applications. +The Keptn Lifecycle Toolkit adds the concept of applications +defined as a set of workloads that can be executed. +A `KeptnApp` resource is added +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 +[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/). +This allows you to use the KLT observability features for existing resources +without manually populating any Keptn related resources. + +## Example + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnApp +metadata: + name: podtato-head + namespace: podtato-kubectl +spec: + version: "1.3" + workloads: + - name: podtato-head-left-arm + version: 0.1.0 + - name: podtato-head-left-leg + version: 1.2.3 + postDeploymentTasks: + - post-deployment-hello + preDeploymentEvaluations: + - my-prometheus-definition +``` + +## Files + +## Differences between versions + +The `spec.Revision` field is introduced in v1alpha2. + +## See also + +[Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery)