Skip to content

Commit

Permalink
docs: fix formatting in CRD reference pages (#2954)
Browse files Browse the repository at this point in the history 
Signed-off-by: Meg McRoberts <[email protected]>
  • Loading branch information
@StackScribe
StackScribe authored Feb 5, 2024
1 parent f9a72b9 commit 634e055
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 68 deletions.
2 changes: 2 additions & 0 deletions docs/docs/reference/crd-reference/evaluationdefinition.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ spec:
```
## Fields
<!-- markdownlint-disable MD007 -->
* **apiVersion** -- API version being used.
Must be `v1alpha3` or later for this syntax.
Expand Down Expand Up @@ -60,6 +61,7 @@ spec:
This is used to define success or failure criteria
for the referenced `KeptnMetric` in order to pass or fail
the pre- and post-evaluation stages
<!-- markdownlint-enable MD007 -->

## Usage

Expand Down
71 changes: 37 additions & 34 deletions docs/docs/reference/crd-reference/metric.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,49 +37,52 @@ spec:
```
## Fields
<!-- markdownlint-disable MD007 -->
* **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](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **namespace** -- Namespace of the application using this metric.
* **name** -- Unique name of this metric.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.
* **namespace** -- Namespace of the application using this metric.

* **spec**
* **provider.name** (required) --
Name of this instance of the data source
from which the metric is collected.
This value must match the value of the `metadata.name` field
of the corresponding [KeptnMetricsProvider](metricsprovider.md) 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** (required) -- String in the provider-specific query language,
used to obtain a metric.

* **fetchIntervalSeconds** (required) -- Number of seconds between updates of the metric.
* **range**
* **interval** -- Timeframe for which the metric is 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.
* **provider.name** (required) --
Name of this instance of the data source
from which the metric is collected.
This value must match the value of the `metadata.name` field
of the corresponding [KeptnMetricsProvider](metricsprovider.md) 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** (required) -- String in the provider-specific query language,
used to obtain a metric.

* **fetchIntervalSeconds** (required) --
Number of seconds between updates of the metric.
* **range**
* **interval** -- Timeframe for which the metric is 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.
<!-- markdownlint-enable MD007 -->

## Usage

Expand Down
75 changes: 41 additions & 34 deletions docs/docs/reference/crd-reference/metricsprovider.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,13 @@ comments: true
KeptnMetricsProvider defines an instance of the data provider
(such as Prometheus, Dynatrace, or Datadog)
that is used by the [KeptnMetric](metric.md) resource.
One Keptn application can perform evaluations based on metrics

One Keptn application can perform
traces, evaluations, and analyses based on metrics
from more than one data provider
and, beginning with the v1alpha3 API version,
can use more than one instance of each data provider.
To implement this, create a KeptnMetricsProvider resource
To implement this, create a `KeptnMetricsProvider` resource
for each instance of each data provider being used,
then reference the appropriate provider
for each metric definition by its name.
Expand All @@ -34,38 +36,40 @@ spec:
```
## Fields
<!-- markdownlint-disable MD007 -->
* **apiVersion** -- API version being used.
`
* **kind** -- Resource type.
Must be set to KeptnMetricsProvider

* **metadata**
* **name** -- Unique name of this provider,
used to reference the provider for the
[KeptnEvaluationDefinition](evaluationdefinition.md)
and [KeptnMetric](metric.md) resources.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.

For example, you might define `dev-prometheus`
for the Prometheus instance that monitors the development deployment,
and `qa-prometheus` for the Prometheus instance
that monitors the Prometheus instance that monitors the QA deployment,
and `prod-dynatrace` for the Dynatrace instance
that monitors the production deployment.

* **namespace** -- Namespace where this provider is used.
* **name** -- Unique name of this provider,
used to reference the provider for the
[KeptnEvaluationDefinition](evaluationdefinition.md)
and [KeptnMetric](metric.md) resources.
Names must comply with the
[Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
specification.

For example, you might define `dev-prometheus`
for the Prometheus instance that monitors the development deployment,
and `qa-prometheus` for the Prometheus instance
that monitors the Prometheus instance that monitors the QA deployment,
and `prod-dynatrace` for the Dynatrace instance
that monitors the production deployment.

* **namespace** -- Namespace where this provider is used.

* **spec**

* **type** (required) -- The type of data provider for this instance
* **targetServer** (required) -- URL of the data provider, enclosed in double quotes
* **secretKeyRef**
* **name:** -- Name of the Secret used by the provider
* **key:** -- Key of the Secret from which to select
* **optional** -- Specify whether the Secret or its key must be defined
* **type** (required) -- The type of data provider for this instance
* **targetServer** (required) -- URL of the data provider, enclosed in double quotes
* **secretKeyRef**
* **name:** -- Name of the Secret used by the provider
* **key:** -- Key of the Secret from which to select
* **optional** -- Specify whether the Secret or its key are required
<!-- markdownlint-enable MD007 -->

## Usage

Expand All @@ -74,20 +78,22 @@ in the same namespace as the
[KeptnMetric](metric.md)
resources that are associated with it.
KeptnMetric resources are used to generate metrics for the cluster
and are used as the SLI (Service Level Indicator) for
and are used as the SLI (Service Level Indicator) for the
[KeptnEvaluationDefinition](evaluationdefinition.md)
resources that are used for pre- and post-deployment evaluations.
and
[AnalysisValueTemplate](analysisvaluetemplate.md)
resources.

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

Metrics providers may require authentication data.
These can be stored in a Secret and referenced in the KeptnMetricsProvider.
These can be stored in a Secret and referenced in the `KeptnMetricsProvider`.
Those Secret resources need to be configured differently for each metrics provider.
The Secret holding the data must have a specific structure
and contain the required data fields.
Expand All @@ -105,7 +111,7 @@ the authentication data looks like the following:
```

> **Note**
Setting the `.spec.secretKeyRef.key` field in KeptnMetricsProvider is not necessary,
Setting the `.spec.secretKeyRef.key` field in `KeptnMetricsProvider` is not necessary,
as `user` and `password` key names are required to be present in the linked Secret.
Setting this field won't have any effect.

Expand All @@ -119,7 +125,7 @@ the authentication data looks like the following:
```

> **Note**
Setting the `.spec.secretKeyRef.key` field in KeptnMetricsProvider is not necessary,
Setting the `.spec.secretKeyRef.key` field in `KeptnMetricsProvider` is not necessary,
as `DD_CLIENT_API_KEY` and `DD_CLIENT_API_KEY` key names must be
present in the linked Secret.
Setting this field has no effect.
Expand Down Expand Up @@ -173,13 +179,14 @@ spec:
```

Also note that, for the v1alpha1 and v1alpha2 API versions,
KeptnMetricsProvider only specifies the provider
for the KeptnMetric resource.
`KeptnMetricsProvider` only specifies the provider
for the `KeptnMetric` resource.
Beginning with `v1alpha3` API version,
KeptnMetricsProvider is also used to specify the provider
`KeptnMetricsProvider` is also used to specify the provider
for the KeptnEvaluationDefinition resource.

## See also

* [KeptnEvaluationDefinition](evaluationdefinition.md)
* [AnalysisValueTemplate](analysisvaluetemplate.md)
* [KeptnMetric](metric.md)

0 comments on commit 634e055

Please sign in to comment.