From eea908f9885b386305fbfa804cf719f57bb73c4f Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 2 Feb 2024 00:50:14 -0800 Subject: [PATCH] docs: add KeptnAppContext ref page; update KeptnApp ref page (#2894) Signed-off-by: Meg McRoberts Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Co-authored-by: Florian Bacher Co-authored-by: Moritz Wiesinger Signed-off-by: Florian Bacher --- docs/docs/reference/crd-reference/app.md | 143 +++++++-------- .../reference/crd-reference/appcontext.md | 169 ++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 242 insertions(+), 71 deletions(-) create mode 100644 docs/docs/reference/crd-reference/appcontext.md diff --git a/docs/docs/reference/crd-reference/app.md b/docs/docs/reference/crd-reference/app.md index 6804dd4f1f..1df2607d87 100644 --- a/docs/docs/reference/crd-reference/app.md +++ b/docs/docs/reference/crd-reference/app.md @@ -4,18 +4,11 @@ comments: true # KeptnApp -A `KeptnApp` resource lists all the [workloads](https://kubernetes.io/docs/concepts/workloads/) -that constitute a logical application. -It contains information about: - -- All [workloads](https://kubernetes.io/docs/concepts/workloads/) and checks - that are associated with a Keptn application -- A list of tasks and evaluations to be executed - pre- and post-deployment. -- Tasks referenced by `KeptnApp` are defined in a - [KeptnTaskDefinition](taskdefinition.md) resource. - `KeptnApp` identifies the task by the value of the `metadata.name` field - and does not need to understand what runner is used to define the task. +A `KeptnApp` resource is auto-generated to list all the +[workloads](https://kubernetes.io/docs/concepts/workloads/) +that constitute a logical Keptn application +and to work with the corresponding +[KeptnAppContext](appcontext.md) resource. ## Synopsis @@ -25,6 +18,8 @@ kind: KeptnApp metadata: name: namespace: + labels: + app.kubernetes.io/managed-by: keptn spec: version: "x.y" revision: x @@ -33,14 +28,6 @@ spec: version: - name: version: - preDeploymentTasks: - - - postDeploymentTasks: - - - preDeploymentEvaluations: - - - postDeploymentEvaluations: - - ``` ## Fields @@ -54,60 +41,42 @@ when the app discovery feature generates the `KeptnApp` resource: - **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. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + This value is the `name` assigned to the + `keptn.sh/app` or `app.kubernetes.io/part-of` + label or annotation for the workloads included in this `KeptnApp`. + If a `KeptnAppContext` resource is associated with this resource, + it must have the same `name` as this `KeptnApp`. - **namespace** -- Namespace of this application. - + If a `KeptnAppContext` resource is associated with this resource, + it must have the same `namespace` as this `KeptnApp`. + - **labels** + - **app-kubernetes.io/managed-by: keptn** -- + Tells Keptn that this resource was autogenerated, + which is always the case for the `v1beta1` version. - **spec** - **version** (required) -- 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. - See - [Restart an Application Deployment](../../guides/restart-application-deployment.md) - for a longer discussion of this. + 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. + See + [Restart an Application Deployment](../../guides/restart-application-deployment.md) + for a longer discussion of this. - **workloads** - **name** (required) -- 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](https://kubernetes.io/docs/concepts/workloads/) - associated with this Keptn application. - - **version** (required) -- version number for this [workload](https://kubernetes.io/docs/concepts/workloads/). - Changing this number causes a new execution - of checks for this [workload](https://kubernetes.io/docs/concepts/workloads/) only, - not the entire application. - -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 - 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 - as part of the pre-deployment stage. - Evaluation names must match the value of the `metadata.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 `metadata.name` field - for the associated [KeptnEvaluationDefinition](evaluationdefinition.md) - resource. + [workload](https://kubernetes.io/docs/concepts/workloads/). + Each [workload](https://kubernetes.io/docs/concepts/workloads/) + associated with this Keptn application has one entry. + - **version** (required) -- version number for this + [workload](https://kubernetes.io/docs/concepts/workloads/). + Changing this number causes a new execution + of checks for this [workload](https://kubernetes.io/docs/concepts/workloads/) only, + not the entire application. ## Usage @@ -165,14 +134,46 @@ spec: ## Differences between versions -- The `spec.revision` field is introduced in v1alpha2. -- The pre/post-deployment tasks and evaluations are not -supported anymore in v1beta1. +The synopsis of the `KeptnApp` resource +is changed in the `v1beta1` API version: + +- The `apiVersion` field now references the `v1beta1` version + of the `lifecycle.keptn.sh` API. +- `KeptnApp` is + [autogenerated](../../guides/auto-app-discovery.md); + you cannot create it manually by applying a manifest. +- The `app.kubernetes.io/managed-by: keptn` label or annotation + is always used for the `v1beta1` library + because the `KeptnApp` resource is always autogenerated. + In earlier releases, this label was not included in `KeptnApp` resources + that were created by applying a manifest + that had been created manually. +- If you want to use a `KeptnAppContext` resource with your application, + the `name` and `namespace` fields + are taken from the annotations of the deployed Kubernetes workloads. + The corresponding `KeptnAppContext` resource (if any), + must have identical values for these fields. +- The `metadata.version` field is now completely managed by Keptn. + You do not increment this value to cause + a new execution of tasks and evaluations; + the only way to trigger a new execution is to increment + the `spec.version` field for the `KeptnApp` resource. +- The pre/post-deployment tasks and evaluations are now defined in the + [KeptnAppContext](appcontext.md) + resource rather than in the `KeptnApp` resource. + +`KeptnApp` resources that were completely autogenerated +for earlier versions are converted automatically to the new structure. +You must manually migrate older `KeptnApp` resources +that were created manually +or that were manually edited +to add pre/post-deployment tasks and evaluations. For more information please refer to the [migration section](../../migrate/keptnapp/index.md). ## See also +- [KeptnAppContext](appcontext.md) - [KeptnTaskDefinition](taskdefinition.md) - [KeptnEvaluationDefinition](evaluationdefinition.md) - [Deployment tasks](../../guides/tasks.md) diff --git a/docs/docs/reference/crd-reference/appcontext.md b/docs/docs/reference/crd-reference/appcontext.md new file mode 100644 index 0000000000..f6f4bafa33 --- /dev/null +++ b/docs/docs/reference/crd-reference/appcontext.md @@ -0,0 +1,169 @@ +--- +comments: true +--- + +# KeptnAppContext + +The `KeptnAppContext` custom resource works with the corresponding +[KeptnApp](app.md) resource +that has the same name and is located in the same namespace. +It allows you to + +- Add metadata and links to traces for a specific application. + This enables you to enrich your traces with additional information that + you can use to understand and analyze + the performance of your applications. + +- Define tasks and evaluations that run + before or after the deployment of the `KeptnApp`. + +## Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v1beta1 +kind: KeptnAppContext +metadata: + name: + namespace: +spec: + metadata: + + spanLinks: + - "" + preDeploymentTasks: + - + postDeploymentTasks: + - + preDeploymentEvaluations: + - + postDeploymentEvaluations: + - +``` + +## Fields + + +- **apiVersion** -- API version being used + Must be set to `lifecycle.keptn.sh/v1beta1` +- **kind** -- Resource type + Must be set to `KeptnAppContext` + +- **metadata** + - **name** -- Unique name of this `KeptnAppContext` resource. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification + and match the `name` given to the associated `KeptnApp` resource. + - **namespace** -- Namespace of this application. + This must match the `namespace` given to + the associated `KeptnApp` resource. +- **spec** + - **metadata** -- list of key-value pairs + that are propagated to the application trace as attributes. + For example, the following lines add the `commit-id` + and `author` information to the `KEPTN_CONTEXT` + of the workload or `KeptnApp` where it is specified: + + ```yaml + spec: + metadata: + commit-id: "1234" + author: "myUser" + ``` + + - **spanLinks** -- List of OpenTelemetry span links + that connect multiple traces. + For example, this can be used to connect + deployments of the same application + through different stages. + You can retrieve the value to use + from the JSON representation of the trace in Jaeger. + The structure of this is: + + ```yaml + 00---01 + ``` + + After you add this field to your `KeptnAppContext` manifest, + you must increment the `revision` number + of the corresponding `KeptnApp` resource + and apply the manifest to store the information in the traces. + +The remaining fields are required only when implementing +the release lifecycle management feature. +If used, these fields must be populated manually: + +- **spec** + + - **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 + 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 + as part of the pre-deployment stage. + Evaluation names must match the value of the `metadata.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 `metadata.name` field + for the associated [KeptnEvaluationDefinition](evaluationdefinition.md) + resource. + +## Usage + +`KeptnAppContext` lists the tasks and evaluations +to be executed pre/post-deployment. +Tasks referenced by `KeptnAppContext` are defined in a +[KeptnTaskDefinition](taskdefinition.md) +resource. +`KeptnAppContext` identifies each task +by the value of the `metadata.name` field +and does not need to understand what runner is used to define the task. +Similarly, evaluations referenced are defined in a +[KeptnEvaluationDefinition](evaluationdefinition.md) +resource and identified by the value of the `metadata.name` field; +`KeptnAppContext` does not need to understand +the data source or query being used for the evaluation. + +## Example + +```yaml +apiVersion: lifecycle.keptn.sh/v1beta1 +kind: KeptnAppContext +metadata: + name: podtato-head + namespace: podtato-kubectl +spec: + preDeploymentTasks: + - container-sleep + - python-secret +``` + +## Files + +[KeptnAppContext](../api-reference/lifecycle/v1beta1/index.md#keptnappcontext) + +## Differences between versions + +The `KeptnAppContext` resource is new in the `v1beta1` version +of the lifecycle operator. + +## See also + +- [KeptnApp](app.md) +- [KeptnTaskDefinition](taskdefinition.md) +- [KeptnEvaluationDefinition](evaluationdefinition.md) +- [Deployment tasks](../../guides/tasks.md) +- [Architecture of KeptnWorkloads and KeptnTasks](../../components/lifecycle-operator/keptn-apps.md) +- Getting started with + [Release Lifecycle Management](../../getting-started/lifecycle-management.md) +- [Use Keptn automatic app discovery](../../guides/auto-app-discovery.md) +- [Restart an Application Deployment](../../guides/restart-application-deployment.md) diff --git a/mkdocs.yml b/mkdocs.yml index ebd8a3d4d0..4d2548ed74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -161,6 +161,7 @@ nav: - AnalysisDefinition: docs/reference/crd-reference/analysisdefinition.md - AnalysisValueTemplate: docs/reference/crd-reference/analysisvaluetemplate.md - KeptnApp: docs/reference/crd-reference/app.md + - KeptnAppContext: docs/reference/crd-reference/appcontext.md - KeptnConfig: docs/reference/crd-reference/config.md - KeptnEvaluationDefinition: docs/reference/crd-reference/evaluationdefinition.md - KeptnMetric: docs/reference/crd-reference/metric.md