diff --git a/docs/content/en/docs/concepts/apps/_index.md b/docs/content/en/docs/concepts/apps/_index.md index 8600d420db..6a058b22b8 100644 --- a/docs/content/en/docs/concepts/apps/_index.md +++ b/docs/content/en/docs/concepts/apps/_index.md @@ -32,3 +32,96 @@ spec: 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/concepts/apps/assets/trace.png b/docs/content/en/docs/concepts/apps/assets/trace.png new file mode 100644 index 0000000000..84254826c9 Binary files /dev/null and b/docs/content/en/docs/concepts/apps/assets/trace.png differ