Integrate Keptn with your applications
Keptn works on top of the default scheduler for the cluster, so it can trace all activities of all deployment workloads on the cluster, no matter what tool is used for the deployment. This same mechanism allows Keptn to inject pre- and post-deployment checks into all deployment workloads. Keptn monitors resources that have been applied into the Kubernetes cluster and reacts if it finds a workload with special annotations/labels. Keptn uses metadata that is added to the Kubernetes workloads to identify the workloads of interest.
To integrate Keptn with your applications:
- You must first install and enable Keptn.
- Annotate or label your workloads with either Keptn or Kubernetes keys.
Note: Annotations are not required if you are only using the
metrics-operatorcomponent of Keptn to observe Keptn metrics.
Keptn automatically discovers
based on the annotations or labels.
This enables the Keptn observability features
(based on OpenTelemetry) for existing applications,
without additional Keptn configuration.
Keptn monitors your
resources in the namespaces where Keptn is enabled.
If Keptn finds any of these resources and the resource has either
keptn.sh or the
it creates appropriate
resources for the version it detects.
The basic keptn.sh keys that can be used for annotations or labels are:
keptn.sh/workload: myAwesomeWorkload keptn.sh/version: myAwesomeWorkloadVersion keptn.sh/app: myAwesomeAppName
Alternatively, you can use Kubernetes keys for annotations or labels. These are part of the Kubernetes Recommended Labels:
app.kubernetes.io/name: myAwesomeWorkload app.kubernetes.io/version: myAwesomeWorkloadVersion app.kubernetes.io/part-of: myAwesomeAppName
These keys are defined as:
app.kubernetes.io/name: Determines the name of the generated KeptnWorkload resource.
app.kubernetes.io/version: Determines the version of the
KeptnWorkloadthat represents the Workload. If the Workload has no
versionannotation/labels and the pod has only one container, Keptn takes the image tag as version (unless it is “latest”).
app.kubernetes.io/part-of: Determines the name of the generated
KeptnApprepresenting your Application. All Workloads that share the same value for this label are consolidated into the same
Keptn automatically generates appropriate
resources that are used for observability,
based on whether the
annotation/label is populated:
If either of these annotations/labels are populated, Keptn automatically generates a
KeptnAppresource that includes all workloads that have the same annotation/label, thus creating a
KeptnAppresource for each defined grouping
If only the
versionannotations/labels are available (in other words, neither the
app.kubernetes.io/part-ofannotation/label is populated), Keptn creates a
KeptnAppresource for each
KeptnWorkloadand your observability output traces the individual
Keptnworkloadresources but not the combined workloads that constitute your deployed application.
Keptn Applications and Keptn Workloads
for architectural information about how
Annotations vs. labels
- 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
- 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,
keptn.sh keys take precedence over
In other words:
- The operator first checks if the
keptn.shkey is present in the annotations, and then in the labels.
- If neither is the case, it looks for the
app.kubernetes.ioequivalent, again first in the annotations, then in the labels.
In general, annotations are more appropriate than labels for integrating Keptn 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 accommodate 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
resources for each evaluation you want.
KeptnEvaluationDefinitioncompares the value of a
KeptnMetricto the threshold that is specified.
- You will also need to define the necessary
resource for each instance of each data source
used for the
KeptnEvaluationDefinitionresources you define.
- Define a
resource for each task you want to execute.
KeptnTaskDefinitionresources 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 for more information.
- Annotate your Workloads Deployments, StatefulSets, and DaemonSets to include each evaluation and task you want run for specific workloads.
- Manually edit all
to specify evaluations and tasks to be run for the
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
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:
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 called KeptnTaskDefinition resources These 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.
If everything is fine, the deployment continues and afterward, a Slack notification is sent with the result of the deployment
Use Keptn automatic app discovery
The automatically generated
aggregates the workloads to include in the application,
based on annotations made to the workloads themselves.
This enables you to run Keptn observability features on your cluster.
Afterward, you can monitor the status of the deployment using a command like the following:
kubectl get keptnworkloadinstance -n podtato-kubectl -w
KeptnApp file includes
that names this
KeptnApp and identifies the Namespace where it resides.
metadata: name: simpleapp namespace: simplenode-dev
It also includes a
that defines the workloads to be included.
Pre-/post-deployment tasks and evaluations for the
can also be added to this resource manually
but this is not required for observability.
As an example, consider the following application, consisting of multiple deployments, which is going to be deployed into a Keptn-enabled namespace. Note that:
- Keptn is enabled for the namespace where your application runs.
Deploymentworkloads are annotated appropriately. This example does not use other workloads.
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 results in the creation
of the following
apiVersion: lifecycle.keptn.sh/v1alpha2 kind: KeptnApp metadata: name: podtato-head namespace: podtato-kubectl annotations: app.kubernetes.io/managed-by: "klt" spec: version: "<version string based on a hash of all containing workloads>" workloads: - name: podtato-head-frontend version: 0.1.0 - name: podtato-head-hat version: 1.1.1
KeptnApp resource created,
you get observability of your application’s deployments
by using the OpenTelemetry tracing features
that are provided by Keptn:
Example of pre- and post-deployment actions
To run the example, use the following commands:
cd ./examples/podtatohead-deployment/ kubectl apply -f .
Afterward, you can monitor the status of the deployment using
kubectl get keptnworkloadinstance -n podtato-kubectl -w
The deployment for a Workload stays in a
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.