Skip to content

KeptnApp

The auto-generated KeptnApp resource aggregates all the workloads that constitute a logical Keptn application, based on the annotations made to the workloads.

Synopsis

apiVersion: lifecycle.keptn.sh/v1
kind: KeptnApp
metadata:
  name: <app-name>
  namespace: <application-namespace>
  labels:
    app.kubernetes.io/managed-by: keptn
spec:
  version: "x.y"
  revision: x
  workloads:
    - name: <workload1-name>
      version: <version-string>
    - name: <workload2-name>
      version: <version-string>

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

  • metadata

    • name -- Unique name of this application. Names must comply with the Kubernetes Object Names and IDs 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 v1 version.
  • spec
    • version (required) -- version of the Keptn application.
    • 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 for a longer discussion of this.
    • workloads
      • name (required) -- name of this Kubernetes workload. Each workload associated with this Keptn application has one entry.
      • version (required) -- version number for this workload. Changing this number causes a new execution of checks for this workload only, not the entire application.

Usage

Kubernetes defines workloads but does not define applications. Keptn 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.

A KeptnApp resource is created automatically, using the automatic application discovery feature to generate a KeptnApp resource based on the 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.

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

This shows an example v1 KeptnApp resource with the corresponding KeptnAppContext resource.

apiVersion: lifecycle.keptn.sh/v1
kind: KeptnApp
metadata:
  name: "some-keptn-app"
  namespace: "my-app-ns"
  labels:
    app.kubernetes.io/managed-by: keptn # added annotation
spec:
  version: "1.2.3"
  workloads:
    - name: podtato-head-left-arm
      version: 0.2.7
# removed pre/post-deployment tasks and evaluations
---
apiVersion: lifecycle.keptn.sh/v1
kind: KeptnAppContext
metadata:
  name: "some-keptn-app" # created a resource with the same name as KeptnApp
  namespace: "my-app-ns"
spec:
  preDeploymentTasks:    # moved pre/post-deployment tasks and evaluations
    - pre-deployment-task
  preDeploymentEvaluations:
    - pre-deployment-evaluation
  postDeploymentTasks:
    - post-deployment-task
  postDeploymentEvaluations:
    - post-deployment-evaluation

Files

Differences between versions

The synopsis of the KeptnApp resource is changed in the v1beta1 and newer API versions:

  • KeptnApp is autogenerated; 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 and newer versions 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 and is computed as the hash of all workloads versions. 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.revision field for the KeptnApp resource.
  • The pre/post-deployment tasks and evaluations are now defined in the KeptnAppContext resource rather than in the KeptnApp resource.

KeptnApp resources that were completely autogenerated for earlier versions are automatically converted 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.

See also