docs: update docs for multi metrics provider support, fix API referen…

…ce generator (#1251) Co-authored-by: Florian Bacher <[email protected]> Co-authored-by: Meg McRoberts <[email protected]>
keptn · Apr 20, 2023 · 1dfd653 · 1dfd653
1 parent 80b46c2
commit 1dfd653
Show file tree

Hide file tree

Showing 12 changed files with 367 additions and 42 deletions.
diff --git a/.github/scripts/generate-crd-docs/generate-crd-docs.sh b/.github/scripts/generate-crd-docs/generate-crd-docs.sh
@@ -10,7 +10,8 @@
 # renovate: datasource=github-releases depName=elastic/crd-ref-docs
 GENERATOR_VERSION=master
 API_DOMAIN="keptn.sh"
-API_ROOT='operator/apis/'
+OPERATOR_API_ROOT='operator/apis/'
+METRICS_API_ROOT='metrics-operator/api/'
 TEMPLATE_DIR='.github/scripts/generate-crd-docs/templates'
 RENDERER='markdown'
 RENDERER_CONFIG_FILE='.github/scripts/generate-crd-docs/crd-docs-generator-config.yaml'
@@ -25,8 +26,8 @@ fi
 
 echo "Running CRD docs auto-generator..."
 
-for api_group in "$API_ROOT"*; do
-  sanitized_api_group="${api_group#$API_ROOT}"
+for api_group in "$OPERATOR_API_ROOT"*; do
+  sanitized_api_group="${api_group#$OPERATOR_API_ROOT}"
   INDEX_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/_index.md"
 
   if [ ! -f "$INDEX_PATH" ]; then
@@ -39,13 +40,13 @@ for api_group in "$API_ROOT"*; do
   fi
 
   for api_version in "$api_group"/*; do
-    sanitized_api_version="${api_version#$API_ROOT$sanitized_api_group/}"
+    sanitized_api_version="${api_version#$OPERATOR_API_ROOT$sanitized_api_group/}"
 
     OUTPUT_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/$sanitized_api_version"
 
     echo "Arguments:"
     echo "TEMPLATE_DIR: $TEMPLATE_DIR"
-    echo "API_ROOT: $API_ROOT"
+    echo "OPERATOR_API_ROOT: $OPERATOR_API_ROOT"
     echo "API_GROUP: $sanitized_api_group"
     echo "API_VERSION: $sanitized_api_version"
     echo "RENDERER: $RENDERER"
@@ -65,3 +66,43 @@ for api_group in "$API_ROOT"*; do
     echo "---------------------"
   done
 done
+
+# Metrics API
+sanitized_api_group="metrics"
+INDEX_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/_index.md"
+
+if [ ! -f "$INDEX_PATH" ]; then
+  echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..."
+  # Use sanitized_api_group and make first char uppercase
+  API_GROUP="$(tr '[:lower:]' '[:upper:]' <<< "${sanitized_api_group:0:1}")${sanitized_api_group:1}"
+  export API_GROUP
+  envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH"
+  unset API_GROUP
+fi
+
+for api_version in "$METRICS_API_ROOT"*; do
+  sanitized_api_version="${api_version#$METRICS_API_ROOT}"
+
+  OUTPUT_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/$sanitized_api_version"
+
+  echo "Arguments:"
+  echo "TEMPLATE_DIR: $TEMPLATE_DIR"
+  echo "METRICS_API_ROOT: $METRICS_API_ROOT"
+  echo "API_GROUP: $sanitized_api_group"
+  echo "API_VERSION: $sanitized_api_version"
+  echo "RENDERER: $RENDERER"
+  echo "RENDERER_CONFIG_FILE: $RENDERER_CONFIG_FILE"
+  echo "OUTPUT_PATH: $OUTPUT_PATH/_index.md"
+
+  echo "Creating docs folder $OUTPUT_PATH..."
+  mkdir -p "$OUTPUT_PATH"
+
+  echo "Generating CRD docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..."
+  crd-ref-docs \
+    --templates-dir "$TEMPLATE_DIR" \
+    --source-path="./$api_version" \
+    --renderer="$RENDERER" \
+    --config "$RENDERER_CONFIG_FILE" \
+    --output-path "$OUTPUT_PATH/_index.md"
+  echo "---------------------"
+done
diff --git a/docs/content/en/docs/concepts/metrics/_index.md b/docs/content/en/docs/concepts/metrics/_index.md
@@ -10,59 +10,66 @@ hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
 ### Keptn Metric
 
 A `KeptnMetric` is a CRD representing a metric.
-The metric will be collected from the provider specified in the
-specs.provider.name field.
+The metric is collected from the provider specified in the
+`spec.provider.name` field.
 The query is a string in the provider-specific query language, used to obtain a metric.
-Providing the metrics as CRD into a K8s cluster will facilitate the reusability of this data across multiple components.
-Furthermore, this allows using multiple observability platforms for different metrics.
+Providing the metrics as CRDs in a K8s cluster facilitates the reusability of this data across multiple components.
+Furthermore, this allows using multiple observability platforms for different metrics at the same time.
 
 A `KeptnMetric` looks like the following:
 
 ```yaml
-apiVersion: metrics.keptn.sh/v1alpha1
+apiVersion: metrics.keptn.sh/v1alpha3
 kind: KeptnMetric
 metadata:
   name: keptnmetric-sample
   namespace: podtato-kubectl
 spec:
   provider:
-    name: "prometheus"
+    name: "my-provider"
   query: "sum(kube_pod_container_resource_limits{resource='cpu'})"
   fetchIntervalSeconds: 5
 ```
 
-In this example, the provider is set to `prometheus`, which is one of the currently supported `KeptnMetricProviders`.
+In this example, the provider is set to `my-provider`.
 The provider tells the metrics-operator where to get the value for the `KeptnMetric`, and its configuration looks follows:
 
 ```yaml
-apiVersion: metrics.keptn.sh/v1alpha2
+apiVersion: metrics.keptn.sh/v1alpha3
 kind: KeptnMetricsProvider
 metadata:
-  name: prometheus
+  name: my-provider
 spec:
+  type: prometheus
   targetServer: "http://prometheus-k8s.monitoring.svc.cluster.local:9090"
 ```
 
-Other supported providers are `dynatrace`, and `dql`:
+As you can see, the provider type is set to `prometheus`, which is one of the currently supported `KeptnMetricProviders`.
+By using different names for different providers of the same type, you can fetch metrics from multiple
+provider instances at the same time.
+
+Other supported provider types are `dynatrace`, `datadog`, and `dql`:
 
 ````yaml
-apiVersion: metrics.keptn.sh/v1alpha2
+apiVersion: metrics.keptn.sh/v1alpha3
 kind: KeptnMetricsProvider
 metadata:
-  name: dynatrace
+  name: my-dynatrace-provider
   namespace: podtato-kubectl
 spec:
+  type: dynatrace
   targetServer: "<dynatrace-tenant-url>"
   secretKeyRef:
     name: dt-api-token
     key: DT_TOKEN
 ---
-apiVersion: metrics.keptn.sh/v1alpha2
+apiVersion: metrics.keptn.sh/v1alpha3
 kind: KeptnMetricsProvider
 metadata:
-  name: dql
+  name: my-dql-provider
   namespace: podtato-kubectl
 spec:
+  type: dql
   secretKeyRef:
     key: CLIENT_SECRET
     name: dt-third-gen-secret 
@@ -72,8 +79,7 @@ spec:
 Keptn metrics can be exposed as OTel metrics via port `9999` of the KLT metrics-operator.
 To expose them, the env
 variable `EXPOSE_KEPTN_METRICS` in the metrics-operator manifest needs to be set to `true`.
-The default value of this variable
-is `true`.
+The default value of this variable is `true`.
 To access the metrics, use the following command:
 
 ```shell
@@ -132,7 +138,7 @@ $ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kube
         "kind": "KeptnMetric",
         "namespace": "podtato-kubectl",
         "name": "keptnmetric-sample",
-        "apiVersion": "metrics.keptn.sh/v1alpha1"
+        "apiVersion": "metrics.keptn.sh/v1alpha3"
       },
       "metric": {
         "name": "keptnmetric-sample",
@@ -166,7 +172,7 @@ $ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kube
         "kind": "KeptnMetric",
         "namespace": "keptn-lifecycle-toolkit-system",
         "name": "keptnmetric-sample",
-        "apiVersion": "metrics.keptn.sh/v1alpha1"
+        "apiVersion": "metrics.keptn.sh/v1alpha3"
       },
       "metric": {
         "name": "keptnmetric-sample",

diff --git a/docs/content/en/docs/crd-ref/metrics/v1alpha2/_index.md b/docs/content/en/docs/crd-ref/metrics/v1alpha2/_index.md
@@ -0,0 +1,137 @@
+---
+title: v1alpha2
+description: Reference information for metrics.keptn.sh/v1alpha2
+---
+<!-- markdownlint-disable -->
+
+## Packages
+- [metrics.keptn.sh/v1alpha2](#metricskeptnshv1alpha2)
+
+
+## metrics.keptn.sh/v1alpha2
+
+Package v1alpha2 contains API Schema definitions for the metrics v1alpha2 API group
+
+### Resource Types
+- [KeptnMetric](#keptnmetric)
+- [KeptnMetricList](#keptnmetriclist)
+- [KeptnMetricsProvider](#keptnmetricsprovider)
+- [KeptnMetricsProviderList](#keptnmetricsproviderlist)
+
+
+
+#### KeptnMetric
+
+
+
+KeptnMetric is the Schema for the keptnmetrics API
+
+_Appears in:_
+- [KeptnMetricList](#keptnmetriclist)
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2`
+| `kind` _string_ | `KeptnMetric`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
+| `spec` _[KeptnMetricSpec](#keptnmetricspec)_ |  |
+
+
+#### KeptnMetricList
+
+
+
+KeptnMetricList contains a list of KeptnMetric
+
+
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2`
+| `kind` _string_ | `KeptnMetricList`
+| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
+| `items` _[KeptnMetric](#keptnmetric) array_ |  |
+
+
+#### KeptnMetricSpec
+
+
+
+KeptnMetricSpec defines the desired state of KeptnMetric
+
+_Appears in:_
+- [KeptnMetric](#keptnmetric)
+
+| Field | Description |
+| --- | --- |
+| `provider` _[ProviderRef](#providerref)_ | Provider represents the provider object |
+| `query` _string_ | Query represents the query to be run |
+| `fetchIntervalSeconds` _integer_ | FetchIntervalSeconds represents the update frequency in seconds that is used to update the metric |
+
+
+
+
+#### KeptnMetricsProvider
+
+
+
+KeptnMetricsProvider is the Schema for the keptnmetricsproviders API
+
+_Appears in:_
+- [KeptnMetricsProviderList](#keptnmetricsproviderlist)
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2`
+| `kind` _string_ | `KeptnMetricsProvider`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
+| `spec` _[KeptnMetricsProviderSpec](#keptnmetricsproviderspec)_ |  |
+
+
+#### KeptnMetricsProviderList
+
+
+
+KeptnMetricsProviderList contains a list of KeptnMetricsProvider
+
+
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2`
+| `kind` _string_ | `KeptnMetricsProviderList`
+| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
+| `items` _[KeptnMetricsProvider](#keptnmetricsprovider) array_ |  |
+
+
+#### KeptnMetricsProviderSpec
+
+
+
+KeptnMetricsProviderSpec defines the desired state of KeptnMetricsProvider
+
+_Appears in:_
+- [KeptnMetricsProvider](#keptnmetricsprovider)
+
+| Field | Description |
+| --- | --- |
+| `targetServer` _string_ |  |
+| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#secretkeyselector-v1-core)_ |  |
+
+
+
+
+#### ProviderRef
+
+
+
+ProviderRef represents the provider object
+
+_Appears in:_
+- [KeptnMetricSpec](#keptnmetricspec)
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name of the provider |
+
+