Define all workloads and checks associated with an application

A KeptnMetric represents a metric that is collected from a provider. Providing the metrics as a CR in a Kubernetes cluster facilitates the reusability of this data across multiple components and allows using multiple observability platforms for different metrics at the same time.

KeptnMetric CRs are also used as targets for EvaluationDefinition CRs.

Yaml Synopsis

kind: KeptnMetric
  name: <metric-name>
  namespace: <application-namespace>
    name: "<named-provider>"
  query: "<query>"
  fetchIntervalSeconds: <#-seconds>
    interval: "<timeframe>"
      value: <resulting value in human-readable language>
      rawValue: <resulting value, in raw format>
      errMsg: <error details if the query could not be evaluated>
      lastUpdated: <time when the status data was last updated>


  • apiVersion – API version being used. `

  • kind – Resource type. Must be set to KeptnMetric.

  • metadata

    • name – Unique name of this metric. Names must comply with the Kubernetes Object Names and IDs specification.
    • namespace – Namespace of the application using this metric.
  • spec

    • – Name of this instance of the data source from which the metric is collected. This value must match the value of the field of the corresponding KeptnMetricsProvider CRD.

      Assigning your own name to the provider rather than just the type of provider enables you to support multiple instances of a data provider. For example, you might have dev-prometheus as the name of the Prometheus server that monitors the dev deployment and prod-prometheus as the name of the Prometheus server that monitors the production deployment.

    • query – String in the provider-specific query language, used to obtain a metric.

    • fetchIntervalSeconds – Number of seconds between updates of the metric.

    • range

      • interval – Timeframe for which the metric would be queried. Defaults to 5m.
  • status

    • Keptn fills in this information when the metric is evaluated. It always records the time the metric was last evaluated. If the evaluation is successful, this stores the result in both human-readable and raw format. If the evaluation is not successful, this stores error details that you can use to understand the problem such as a forbidden code.


A KeptnMetric resource must be located in the same namespace as the associated KeptnMetricsProvider resource. KeptnMetric resources are used to generate metrics for the cluster and are used as the SLI (Service Level Indicator) for KeptnEvaluationDefinition resources that are used for pre- and post-deployment evaluations.

KeptnEvaluationDefinition resources can reference metrics from any namespace. This means that you can create KeptnMetricsProvider and KeptnMetric resources in a centralized namespace (e.g. in keptn-lifecycle-toolkit-system) and access those metrics in evaluations on all namespaces in the cluster.


This example pulls metrics from the data provider defined as my-provider in the field of the corresponding KeptnMetricsProvider CR.

kind: KeptnMetric
  name: keptnmetric-sample
  namespace: podtato-kubectl
    name: "my-provider"
  query: "sum(kube_pod_container_resource_limits{resource='cpu'})"
  fetchIntervalSeconds: 5
    interval: "5m"


API Reference:

Differences between versions

Beginning with the v1alpha3 API version, Keptn allows you to define multiple instances of the same data source. In earlier versions, you could use multiple data sources but only one instance of each. Consequently, the v1alpha1 and v1alpha2 API versions define the provider field with the type of the data provider (prometheus, dynatrace, or dql) rather than the particular name assigned to the instance of the data provider that is assigned in the KeptnMetricsProvider CR.

So the v1alpha1 and v1alpha2 synopsis of the spec field is:

    name: "prometheus | dynatrace | dql"
  fetchIntervalSeconds: <seconds>
  query: >-

See also

Last modified 2023-11-03: docs: release 0.9.0 (#2396) (fef5826)