Context Metadata
This guide walks you through the usage of context metadata in Keptn.
After reading this guide you will be able to:
- add metadata to applications, workloads and tasks in two ways
- add metadata information about applications to their traces
Introduction
Context metadata in Keptn is defined as all additional information that can be added to applications, workloads and tasks.
Context metadata can be added to your application in either of the following ways:
- Use the
keptn.sh/metadata
annotation in any of your workloads you plan to deploy with Keptn - Apply a
KeptnAppContext
custom resource
In the following section we will explore both.
Common uses of this feature include:
- adding a commit ID or references related to your GitOps and CI-CD tooling
- referencing different stages and actors such as: who committed the change, in what repo, for what ticket...
Before you start
- Install Keptn
- Deploy an application, for instance, you can follow a demo app installation here
To collect traces you will require Jaeger. To visualise and inspect the traces, you can either use the Jaeger UI or Grafana.
- Install Grafana following the instructions in Grafana Setup or the visualization tool of your choice.
- Install Jaeger or a similar tool for traces following the instructions in Jaeger Setup.
Include metadata in workload traces
To enrich workload traces with custom metadata, use the
keptn.sh/metadata
annotation in your
Deployment
resource.
The comma-separated list of key-value pairs specified in the annotation
is added as key-value attributes to the workload trace.
Modify your workload (for example your YAML file containing a Deployment)
adding an annotation with any metadata you prefer.
If you want to add multiple key-value pairs, separate them with commas.
For instance, to add information about a stage and owning team, you could add:
keptn.sh/metadata: "stage=dev,team=my-team"
.
To see the changes Keptn must redeploy: increment the app.kubernetes.io/version
value
(ex. if you are following our getting started guide, change the version
from 0.0.2
to 0.0.3
) or change the keptn.sh/version
value
if you used the Keptn specific labels in your deployment YAML file.
This way, after the re-deployment, the workload trace will contain the stage=dev
attribute.
Include metadata in application traces
Similar to the previous step, custom metadata can also be added to application traces via the KeptnAppContext CRD.
KeptnAppContext
is a custom resource definition in Keptn that allows you to add metadata
and links to traces for a specific application.
This enables you to enrich your Keptn resources and your traces with additional
information, making it easier to understand and analyze
the performance of your applications.
In the .spec.metadata
field you can define multiple key-value pairs, which are propagated
to the application trace as attributes in the same manner as for workloads.
Note The key-value pairs that are added to the application trace are also added to each workload trace that is part of the application. If the same key is specified for both application and workload metadata attributes, values specified for the workload take precedence.
A KeptnAppContext
custom resource looks like the following:
apiVersion: lifecycle.keptn.sh/v1
kind: KeptnAppContext
metadata:
name: keptndemoapp
namespace: keptndemo
spec:
metadata:
commit-id: "1234"
author: "myUser"
After applying the KeptnAppContext
to your cluster, you need to increment the version of your
application by modifying your deployment file and changing the
value of theapp.kubernetes.io/version
field (or keptn.sh/version
if you used the Keptn specific labels earlier).
(Alternatively you could apply the context resource before or together with the workloads.)
After deploying the KeptnAppContext
resource and re-deploying the application,
Keptn triggers another deployment of your application with the new context metadata,
and all traces will contain the new metadata as defined in the above code example.
In other words, you should be able to see the application trace as well as the workload trace
contain the defined metadata as key-value attributes.
What's next?
Congratulations!
You've learned how to use the KeptnAppContext
CRD to add
metadata to applications and their traces.
This can be valuable for understanding the context of your traces and
establishing connections between
different versions and stages of your application.
Explore more about traces on Keptn. The paragraph on linking traces between different application also uses KeptnAppContext.