diff --git a/docs/content/en/docs/crd-ref/_index.md b/docs/content/en/docs/crd-ref/_index.md index b96035fe53..8fd909997d 100644 --- a/docs/content/en/docs/crd-ref/_index.md +++ b/docs/content/en/docs/crd-ref/_index.md @@ -18,7 +18,8 @@ We welcome your input!** Each CRD is an object of an API library. Keptn APIs follow the Kubernetes API versioning scheme. and are themselves composed of objects and sub-objects. -By introducing CRDs, Keptn is extending the base Kubernetes API with new objects and functionality. +By introducing CRDs, Keptn is extending the base Kubernetes API +with new objects and functionality. Keptn APIs follow API versioning conventions recommended by Kubernetes. For more information, see the Kubernetes documentation: diff --git a/docs/content/en/docs/implementing/_index.md b/docs/content/en/docs/implementing/_index.md index a8d31f3f49..68c8f181fb 100644 --- a/docs/content/en/docs/implementing/_index.md +++ b/docs/content/en/docs/implementing/_index.md @@ -12,3 +12,17 @@ This section is under development. Information that is published here has been reviewed for technical accuracy but the format and content is still evolving. We welcome your input!** + +This section provides information about how to implement +various features and functionality with the Keptn Lifecycle Toolkit. +The following topics are covered: + +* Workloads, Applications, and Deployments + +* Observability + + * Evaluations + * [Site metrics](metrics.md) that provides a single entry-point + to site metrics at the application or workload level, + based on one or more standard data providers + * Tracing diff --git a/docs/content/en/docs/implementing/evaluatemetrics.md b/docs/content/en/docs/implementing/evaluatemetrics.md deleted file mode 100644 index 0c70c43172..0000000000 --- a/docs/content/en/docs/implementing/evaluatemetrics.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Evaluate metrics -description: Define all workloads and checks associated with an application -weight: 130 ---- diff --git a/docs/content/en/docs/implementing/metrics.md b/docs/content/en/docs/implementing/metrics.md new file mode 100644 index 0000000000..3bcd345072 --- /dev/null +++ b/docs/content/en/docs/implementing/metrics.md @@ -0,0 +1,169 @@ +--- +title: Keptn Metrics +description: Implement Keptn site metrics +weight: 130 +--- + +Kubernetes provides two metrics servers, +one that is custom, the other external. +However, the Kubernetes metrics servers +only allow you to release a single service on a API; +you cannot use multiple observability platforms +in one namespace for one API. + +Keptn Metrics provides a single entry point to all metrics in the cluster +and allows you to use multiple observability platforms +and, beginning with V0.8.0, +multiple instances of any observability platform. +Keptn Metrics are also application aware +so report data for all workflows that are included in the Keptn application. + +This data can be presented on Grafana +or any standard dashboard application that you configure. + +[More introductory info to come] + +## Keptn metrics basics + +Keptn metrics are implemented with two CRDs: + +* [KeptnMetric](../yaml-crd-ref/metric.md) -- + define the metric to report +* [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) -- + define the data provider to be used for this metric + +## Using OpenTelemetry with Keptn metrics + +Keptn metrics can be exposed as OpenTelemetry (OTel) metrics +via port `9999` of the KLT metrics-operator. + +To expose OTel metrics, +be sure that the `EXPOSE_KEPTN_METRICS` environment variable +in the `metrics-operator` manifest is set to `true`, +which is the default value. + +To access the metrics, use the following command: + +```shell +kubectl port-forward deployment/metrics-operator 9999 -n keptn-lifecycle-toolkit-system +``` + +You can access the metrics from your browser at: + +```http://localhost:9999/metrics``` + +## Accessing Metrics via the Kubernetes Custom Metrics API + +`KeptnMetrics` can also be retrieved via the Kubernetes Custom Metrics API. + +### Using the HorizontalPodAutoscaler + +Use the Kubernetes Custom Metrics API +to refer to Keptnmetrics via the +[Kubernetes HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) +(HPA), +as in the following example: + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: podtato-head-entry + namespace: podtato-kubectl +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: podtato-head-entry + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Object + object: + metric: + name: keptnmetric-sample + describedObject: + apiVersion: metrics.keptn.sh/v1alpha1 + kind: KeptnMetric + name: keptnmetric-sample + target: + type: Value + value: "10" +``` + +See the [Scaling Kubernetes Workloads based on Dynatrace Metrics](https://www.linkedin.com/pulse/scaling-kubernetes-workloads-based-dynatrace-metrics-keptnproject/) +blog post +for a detailed discussion of doing this with Dynatrace metrics. +A similar approach could be used to implement HPA with other data providers. + +### Retrieve KeptnMetric values with kubectl raw + +Use the `kubectl raw` command +to retrieve the values of a `KeptnMetric`, as in the following example: + +```shell +$ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kubectl/keptnmetrics.metrics.sh/keptnmetric-sample/keptnmetric-sample" | jq . + +{ + "kind": "MetricValueList", + "apiVersion": "custom.metrics.k8s.io/v1beta2", + "metadata": {}, + "items": [ + { + "describedObject": { + "kind": "KeptnMetric", + "namespace": "podtato-kubectl", + "name": "keptnmetric-sample", + "apiVersion": "metrics.keptn.sh/v1alpha1" + }, + "metric": { + "name": "keptnmetric-sample", + "selector": { + "matchLabels": { + "app": "frontend" + } + } + }, + "timestamp": "2023-01-25T09:26:15Z", + "value": "10" + } + ] +} +``` + +### Filter on matching labels + +You can filter based on matching labels. +For example, to retrieve all metrics +that are labelled with `app=frontend`, +use the following command: + +```shell +$ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kubectl/keptnmetrics.metrics.sh/*/*?labelSelector=app%3Dfrontend" | jq . + +{ + "kind": "MetricValueList", + "apiVersion": "custom.metrics.k8s.io/v1beta2", + "metadata": {}, + "items": [ + { + "describedObject": { + "kind": "KeptnMetric", + "namespace": "keptn-lifecycle-toolkit-system", + "name": "keptnmetric-sample", + "apiVersion": "metrics.keptn.sh/v1alpha1" + }, + "metric": { + "name": "keptnmetric-sample", + "selector": { + "matchLabels": { + "app": "frontend" + } + } + }, + "timestamp": "2023-01-25T09:26:15Z", + "value": "10" + } + ] +} +``` diff --git a/docs/content/en/docs/implementing/tasks.md b/docs/content/en/docs/implementing/tasks.md new file mode 100644 index 0000000000..2325538e12 --- /dev/null +++ b/docs/content/en/docs/implementing/tasks.md @@ -0,0 +1,99 @@ +--- +title: Working with Keptn tasks +description: Learn how to work with Keptn tasks +icon: concepts +layout: quickstart +weight: 20 +hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +--- + +## Keptn Task Definition + +Keptn tasks are defined in a +[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition/) +CRD. +A task definition includes a function +that defines the action taken by that task. +It can be configured in one of three different ways: + +- inline +- referring to an HTTP script +- referring to another `KeptnTaskDefinition` + +## Parameterized functions + +`KeptnTaskDefinition`s can use input parameters. +Consider the following example: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnTaskDefinition +metadata: + name: slack-notification-dev +spec: + function: + functionRef: + name: slack-notification + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +Note the following about using parameters with functions: + +- The Lifecycle Toolkit passes the values + defined inside the `map` field as a JSON object. +- Multi-level maps are not currently supported. +- The JSON object can be read through the environment variable `DATA` + using `Deno.env.get("DATA");`. + +## Passing secrets to a function + +In the previous example, you see that +Kubernetes +[secrets](https://kubernetes.io/docs/concepts/configuration/secret/) +can be passed to the function +using the `secureParameters` field. + +Here, the `secret` value is the name of the Kubernetes secret, +which contains a field with the key `SECURE_DATA`. +The value of that field is then available to the function's runtime +via an environment variable called `SECURE_DATA`. + +For example, if you have a task function that should make use of secret data, +you must first ensure that the secret containing the `SECURE_DATA` key exists +For example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: deno-demo-secret + namespace: default +type: Opaque +data: + SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar' +``` + +Then, you can make use of that secret as follows: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: deployment-hello + namespace: "default" +spec: + function: + secureParameters: + secret: deno-demo-secret + inline: + code: | + console.log("Deployment Hello Task has been executed"); + + let foo = Deno.env.get('SECURE_DATA'); + console.log(foo); + Deno.exit(0); +``` diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md index 2c71a4fced..efd5c6c776 100644 --- a/docs/content/en/docs/install/_index.md +++ b/docs/content/en/docs/install/_index.md @@ -19,7 +19,7 @@ or as part of an existing production cluster. 1. Understand the [Software versions and resources](reqs.md) that are required 1. [Bring or create your Kubernetes cluster](k8s.md) -1. [Replace the default cert-manager](cert-manager.md) (optional) +1. [Replace the default cert-manager](cert-manager.md) (optional). This step is only required if you want to replace the default KLT cert-manager with another cert-manager. 1. [Install the Keptn Lifecycle Controller](install.md) diff --git a/docs/content/en/docs/tasks/write-tasks/_index.md b/docs/content/en/docs/tasks/write-tasks/_index.md deleted file mode 100644 index 88bed96f31..0000000000 --- a/docs/content/en/docs/tasks/write-tasks/_index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Write Keptn Tasks -description: Learn how to use the Keptn Lifecycle Toolkit and explore basic features. -icon: concepts -layout: quickstart -weight: 20 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - -## Keptn Task Definition - -A `KeptnTaskDefinition` is a CRD used to define tasks that can be run by the Keptn Lifecycle Toolkit -as part of pre- and post-deployment phases of a deployment. -The task definition is a [Deno](https://deno.land/) script. -In the future, we also intend to support other runtimes, especially running a container image directly. - -A task definition can be configured in three different ways: - -- inline -- referring to an HTTP script -- referring to another `KeptnTaskDefinition` - -An inline task definition looks like the following: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: deployment-hello -spec: - function: - inline: - code: | - console.log("Deployment Task has been executed"); -``` - -In the code section, it is possible to define a full-fletched Deno script. - -The runtime can also fetch the script on the fly from a remote webserver. -For this, the CRD should look like the -following: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: hello-keptn-http -spec: - function: - httpRef: - url: -``` - -Finally, `KeptnTaskDefinition` can build on top of other `KeptnTaskDefinition`s. -This is a common use case where a general function can be re-used in multiple places with different parameters. - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: slack-notification-dev -spec: - function: - functionRef: - name: slack-notification - parameters: - map: - textMessage: "This is my configuration" - secureParameters: - secret: slack-token -``` - -As you might have noticed, Task Definitions also have the possibility to use input parameters. -The Lifecycle Toolkit passes the values defined inside the `map` field as a JSON object. -At the moment, multi-level maps are not supported. -The JSON object can be read through the environment variable `DATA` using `Deno.env.get("DATA");`. -Kubernetes secrets can also be passed to the function using the `secureParameters` field. - -Here, the `secret` value is the name of the K8s secret containing a field with the key `SECURE_DATA`. -The value of that field will then be available to the functions runtime via an environment variable called `SECURE_DATA`. - -For example, if you have a task function that should make use of secret data, you must first ensure that the secret -containing the `SECURE_DATA` key exists, as e.g.: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: deno-demo-secret - namespace: default -type: Opaque -data: - SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar' -``` - -Then, you can make use of that secret as follows: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha3 -kind: KeptnTaskDefinition -metadata: - name: deployment-hello - namespace: "default" -spec: - function: - secureParameters: - secret: deno-demo-secret - inline: - code: | - console.log("Deployment Hello Task has been executed"); - - let foo = Deno.env.get('SECURE_DATA'); - console.log(foo); - Deno.exit(0); -``` diff --git a/docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md b/docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md new file mode 100644 index 0000000000..b442fda0af --- /dev/null +++ b/docs/content/en/docs/yaml-crd-ref/evaluationdefinition.md @@ -0,0 +1,104 @@ +--- +title: KeptnEvaluationDefinition +description: Define all workloads and checks associated with an application +weight: 20 +--- + +A `KeptnEvaluationDefinition` defines evaluation tasks +that can be run by the Keptn Lifecycle Toolkit +as part of pre- and post-analysis phases of a workload or application. + +## Yaml Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnEvaluationDefinition +metadata: + name: pre-deployment-hello +spec: + objectives: + - evaluationTarget: ">1" + keptnMetricRef: + name: available-cpus + namespace: some-namespace +``` + +## Fields + +* **apiVersion** -- API version being used. +` +* **kind** -- Resource type. + Must be set to `KeptnEvaluationDefinition` + +* **metadata** + * **name** -- Unique name of this evaluation + such as `pre-deploy-eval` or `post-deploy-resource-eval`. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, (others?) + * Should not include spaces. + +* **spec** + * **source** -- Name of the data provider being used for this evaluation. + The value of the `source` field must match + the string used for the `name` field + in the corresponding [KeptnEvaluationProvider](evaluationprovider.md) CRD. + + Each `KeptnEvaluationDefinition` CRD can use only one data provider; + if you are using multiple data provider, you must create + `KeptnEvaluationProvider` and `KeptnEvaluationDefinition` CRDs for each. + + Currently, you can only access one occurrance of each type of data provider + in your KLT cluster. + + * **objectives** -- define the evaluations to be performed. + Each objective is expressed as a `query` and an `evaluationTarget` value. + + * **query** -- Any query that is supported by the data provider. + * **value** -- Desired value of the query, + expressed as an arithmatic formula, + usually less than (`<`) or greater than (`>`) + +## Usage + +## Examples + +## Files + +API Reference: + +## Differences between versions + +In the `v1alpha1` and `v1alpha2` API versions, +`KeptnEvaluationDefinition` references the `KeptnEvaluationProvider` CRD +to identify the data source associated with this definition +and itself contained the queries +that are now taken from the specified [KeptnMetric](metric.md) CRD. +The synopsis was: + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnEvaluationDefinition +metadata: + name: +spec: + source: prometheus | dynatrace | datadog + objectives: + - name: query-1 + query: "xxxx" + evaluationTarget: <20 + - name: query-2 + query: "yyyy" + evaluationTarget: >4 +``` + +Beginning with `v1alpha3` API version, +`KeptnEvaluationDefinition` references the data source defined +in the [KeptnMetricsProvider](metricsprovider.md) +and the queries are specified in the corresponding +[KeptnMetric](metric.md) CRD +although the `evaluationTarget` is defined in this CRD. + +## See also + +* [KeptnMetricsProvider](metricsprovider.md) +* [KeptnMetric](metric.md) diff --git a/docs/content/en/docs/yaml-crd-ref/evaluationdefnition.md b/docs/content/en/docs/yaml-crd-ref/evaluationdefnition.md deleted file mode 100644 index e054a6e08a..0000000000 --- a/docs/content/en/docs/yaml-crd-ref/evaluationdefnition.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: KeptnEvaluationDefinition -description: Define all workloads and checks associated with an application -weight: 20 ---- diff --git a/docs/content/en/docs/yaml-crd-ref/evaluationprovider.md b/docs/content/en/docs/yaml-crd-ref/evaluationprovider.md index 1f2ad4bc43..5115a74f0b 100644 --- a/docs/content/en/docs/yaml-crd-ref/evaluationprovider.md +++ b/docs/content/en/docs/yaml-crd-ref/evaluationprovider.md @@ -1,5 +1,50 @@ --- -title: KeptnEvaluationProvider +title: KeptnEvaluationProvider (deprecated) description: Define the evaluation provider weight: 13 --- + +In earlier releases of the Lifecycle Toolkit, +`KeptnEvaluationProvider` defined the data provider +used by [KeptnEvaluationDefinition]( + +## Yaml Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnTaskDefinition +metadata: + name: +``` + +## Fields + +* **apiVersion** -- API version being used. +` +* **kind** -- Resource type. + Must be set to `KeptnTaskDefinition` + +* **name** -- Unique name of this task. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, (others?) + * Should not include spaces. + +## Usage + +### Create secret text + +## Examples + +## Files + +API Reference: + +## Differences between versions + +The `KeptnEvaluationProvider` is deprecated in the v1alpha3 API version. +`KeptnEvaluationDefinition` now gets provider information from the +[KeptnMetricsProvider](metricsprovider.md) CR. + +## See also + +* [KeptnEvaluationDefinition](evaluationdefinition) diff --git a/docs/content/en/docs/yaml-crd-ref/metric.md b/docs/content/en/docs/yaml-crd-ref/metric.md index 7d48b8222f..b56b581b90 100644 --- a/docs/content/en/docs/yaml-crd-ref/metric.md +++ b/docs/content/en/docs/yaml-crd-ref/metric.md @@ -3,3 +3,116 @@ title: KeptnMetric description: Define all workloads and checks associated with an application weight: 50 --- + +A `KeptnMetric` represents a metric that is collected from a provider. +Providing the metrics as a CRD into 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. + +A `KeptnMetric` looks like the following: + +## Yaml Synopsis + +```yaml +apiVersion: metrics.keptn.sh/v?alpha? +kind: KeptnMetric +metadata: + name: + namespace: +spec: + provider: + name: "" + query: "" + fetchIntervalSeconds: <#-seconds> +``` + +## Fields + +* **apiVersion** -- API version being used. +` +* **kind** -- Resource type. + Must be set to `KeptnTaskDefinition` + +* **metadata** + * **name** -- Unique name of this metric. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, (others?) + * Should not include spaces. + * **namespace** -- namespace of the application using this metric + +* **spec** + * **provider.name** -- + Name of this instance of the data source + from which the metric is collected. + This value must match the value of the `spec.provider.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** -- String in the provider-specific query language, + used to obtain a metric. + * **fetchIntervalSeconds** -- Number of seconds between ?? + +## Usage + +## Example + +This example pulls metrics from the data provider +defined as `my-provider` in the `spec.provider.name` field +of the corresponding `KeptnMetricsProvider` CRD. + +```yaml +apiVersion: metrics.keptn.sh/v1alpha3 +kind: KeptnMetric +metadata: + name: keptnmetric-sample + namespace: podtato-kubectl +spec: + provider: + name: "my-provider" + query: "sum(kube_pod_container_resource_limits{resource='cpu'})" + fetchIntervalSeconds: 5 + + +## Files + +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` library versions +define the `provider` field with the name 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](metricsprovider.md) CRD. + +So the `v1alpha1` and `v1alpha2` synopsis +of the `spec` field is: + +```yaml +... +spec: + provider: + name: "prometheus | dynatrace | dql" + fetchIntervalSeconds: + query: >- + "" +``` + +## See also + +* [KeptnEvaluationDefinition](evaluationdefinition.md) +* [KeptnMetricsProvider](metricsprovider.md) +* Implementing [Keptn Metrics](../implementing/metrics.md) +* Architecture of the [Keptn Metrics Operator](../concepts/architecture/components/metrics-operator/_index.md) diff --git a/docs/content/en/docs/yaml-crd-ref/metricsprovider.md b/docs/content/en/docs/yaml-crd-ref/metricsprovider.md index 0ca9078a11..873a48f7fe 100644 --- a/docs/content/en/docs/yaml-crd-ref/metricsprovider.md +++ b/docs/content/en/docs/yaml-crd-ref/metricsprovider.md @@ -1,5 +1,123 @@ --- title: KeptnMetricsProvider -description: Define all workloads and checks associated with an application +description: Define data provider used for metrics and evaluations weight: 55 --- + +`KeptnMetricsProvider` defines an instance of the data provider +(such as Prometheus, Dynatrace, or Datadog) +that is used by the [KeptnMetric](metric.md) +and [KeptnEvaluationDefinition](evaluationdefinition.md) CRDs. +One Keptn application can perform evaluations and metrics +from more than one data provider +and, beginning in V0.8.0, +more than one instance of each data provider. +To implement this, create a `KeptnMetricsProvider` CRD +for each instance of each data provider being used +then reference the appropriate provider +for each evaluation or metric definition. + +## Yaml Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnMetricsProvider +metadata: + name: + namespace: +spec: + type: prometheus | dynatrace | dql + targetServer: "" + secretKeyRef: + name: + key: + + +## Fields + +* **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) + and [KeptnMetric](metric.md) CRs. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, (others?) + * Should not include spaces. + + * **namespace** -- Namespace where this provider is used. + +* **spec** + + * **type** -- The type of data provider for this instance + * **targetServer** -- URL of the data provider, enclosed in double quotes + * **secretKeyRef** + * **name:** -- Name of the token for this data provider + * **key:** -- Key for this data provider + + +## Usage + + +## Examples + +### Example 1: Dynatrace data provider + +```yaml +apiVersion: metrics.keptn.sh/v1alpha2 +kind: KeptnMetricsProvider +metadata: + name: dynatrace + namespace: podtato-kubectl +spec: + targetServer: "" + secretKeyRef: + name: dt-api-token + key: DT_TOKEN +``` + +## Files + +API Reference: + +## Differences between versions + +For the `v1alpha1` and `v1alpha2` API versions, +Keptn did not support +using more than one instance of a particular data provider +in the same namespace. +In other words, one namespace could support one instance each +of Prometheus, Dynatrace, and Datadog +but could not support, for example, two instances of Prometheus. + +The synopsis in those older API versions +only specified the `metadata.name` field +that identified the data provider (`prometheus`, `dynatrace`, or `dql`): + +```yaml +apiVersion: metrics.keptn.sh/v1alpha2 +kind: KeptnMetricsProvider +metadata: + name: prometheus | dynatrace |dql + namespace: +spec: + targetServer: "" + secretKeyRef: + name: dt-api-token + key: DT_TOKEN +``` + +Also note that, for the v1alpha1 and v1alpha2 API versions, +`KeptnMetricsProvider` only specifies the provider +for the `KeptnMetrics` CR. +Beginning with `v1alpha3` API version, +`KeptnMetricsProvider` is also used to specify the provider +for the `KeptnEvaluationDefinition` CR. + +## See also + +* [KeptnEvaluationDefinition](evaluationdefinition.md) +* [KeptnMetric](metric.md) diff --git a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md index 877444e902..bbaa30e4a6 100644 --- a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md +++ b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md @@ -3,3 +3,306 @@ title: KeptnTaskDefinition description: Define tasks that can be run pre- or post-deployment weight: 89 --- + +A `KeptnTaskDefinition` defines tasks +that are run by the Keptn Lifecycle Toolkit +as part of the pre- and post-deployment phases of a +[KeptnApp](./app.md). + +## Yaml Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnTaskDefinition +metadata: + name: +spec: + function: + inline | httpRef | functionRef: + [parameters: + map: + textMessage: "This is my configuration"] + [secureParameters: + secret: slack-token] +``` + +## Fields + +* **apiVersion** -- API version being used. +` +* **kind** -- Resource type. + Must be set to `KeptnTaskDefinition` + +* **name** -- Unique name of this task. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, (others?) + * Should not include spaces. + +* **function** -- Code to be executed, + expressed as a [Deno](https://deno.land/) script. + Refer to [function runtime](https://github.com/keptn/lifecycle-toolkit/tree/main/functions-runtime) + for more information about the runtime. + + The `function` can be defined as one of the following: + + * **inline** - Include the actual executable code to execute. + This can be written as a full-fledged Deno script + that is included in this file. + For example: + + ```yaml + function: + inline: + code: | + console.log("Deployment Task has been executed"); + ``` + + * **httpRef** - Specify a Deno script to be executed at runtime + from the remote webserver that is specified. + For example: + + ```yaml + name: hello-keptn-http + spec: + function: + httpRef: + url: "https://www.example.com/yourscript.js" + ``` + + Note that the file referenced is actually JavaScript, + which is essentially the same as a Deno script. + + * **functionRef** -- Execute another `KeptnTaskDefinition` that has been defined. + Populate this field with the value of the `name` field + for the `KeptnTaskDefinition` to be called. + This is commonly used to call a general function + that is used in multiple places, possibly with different parameters. + An example is: + + ```yaml + spec: + function: + functionRef: + name: slack-notification + ``` + + This can also be used to group a set of tasks + into a single `KeptnTaskDefinition`, + such as defining a `KeptnTaskDefinition` for testing. + In this case, it other, existing `KeptnTaskDefinition`s + for each type of test to be run, + specifying each by the value of the `name` field. + +* **parameters** - An optional field to supply input parameters to a function. + The Lifecycle Toolkit passes the values defined inside the `map` field + as a JSON object. + For example: + + ```yaml + spec: + parameters: + map: + textMessage: "This is my configuration" + ``` + + The JSON object can be read + through the `DATA` environment variable using `Deno.env.get("DATA");`. + + Multi-level maps are not supported at this time. + + Currently only one secret can be passed. + The secret must have a `key` called `SECURE_DATA`. + It can be accessed via the environment variable `Deno.env.get("SECURE_DATA")`. + See [Context](#context) for details. + +* **secureParameters** -- An optional field used to pass a Kubernetes secret. + The `secret` value is the Kubernetes secret name + that is mounted into the runtime and made available to functions + using the `SECURE_DATA` environment variable. + For example: + + ```yaml + secureParameters: + secret: slack-token + + See [Create secret text](#create-secret-text) for details. + +## Usage + +A Task is responsible for executing the TaskDefinition of a +[workload](https://kubernetes.io/docs/concepts/workloads/).. +The execution is done by spawning a Kubernetes +[Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) +to handle a single Task. +In its state, it tracks the current status of this Kubernetes Job. + +### Context + +A Kubernetes context is a set of access parameters +that contains a Kubernetes cluster, a user, and a namespace. +For more information, see +[Configure Access to Multiple Clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). + +A context environment variable is available via `Deno.env.get("CONTEXT")`. +It can be used like this: + +```javascript +let context = Deno.env.get("CONTEXT"); + +if (contextdata.objectType == "Application") { + let application_name = contextdata.appName; + let application_version = contextdata.appVersion; +} + +if (contextdata.objectType == "Workload") { + let application_name = contextdata.appName; + let workload_name = contextdata.workloadName; + let workload_version = contextdata.workloadVersion; +} +``` + +### Create secret text + +```yaml +# kubectl create secret generic my-secret --from-literal=SECURE_DATA=foo + +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + // secret_text = "foo" +``` + +This methodology supports multiple variables +by creating a Kubernetes secret with a JSON string: + +```yaml +# kubectl create secret generic my-secret \ +# --from-literal=SECURE_DATA="{\"foo\": \"bar\", \"foo2\": \"bar2\"}" + +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + let secret_text_obj = JSON.parse(secret_text); + // secret_text_obj["foo"] = "bar" + // secret_text_obj["foo2"] = "bar2" +``` + +## Examples + +### Example 1: inline script + +This example defines a full-fledged Deno script +within the `KeptnTaskDefinition` YAML file: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: hello-keptn-inline +spec: + function: + inline: + code: | + let text = Deno.env.get("DATA"); + let data; + let name; + data = JSON.parse(text); + + name = data.name + console.log("Hello, " + name + " new"); +``` + +### Example 2: httpRef script + +This example fetches the Deno script from a remote webserver at runtime: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: hello-keptn-http +spec: + function: + httpRef: + url: "https://www.example.com/yourscript.js" +``` + +For another example, see the +[sample-app](https://github.com/keptn-sandbox/lifecycle-toolkit-examples/blob/main/sample-app/version-1/app-pre-deploy.yaml). + +See the +[sample-app/version-1](https://github.com/keptn-sandbox/lifecycle-toolkit-examples/blob/main/sample-app/version-1/app-pre-deploy.yaml) +PodtatoHead example for a more complete example. + +### Example 3: functionRef + +This example calls another defined task, +illustrating how one `KeptnTaskDefinition` can build +on top of other `KeptnTaskDefinition`s. +In this case, it calls `slack-notification-dev`, +passing `parameters` and `secureParameters` to that other task: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: slack-notification-dev +spec: + function: + functionRef: + name: slack-notification + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +### More examples + +See the [operator/config/samples](https://github.com/keptn/lifecycle-toolkit/tree/main/operator/config/samples) +directory for more example `KeptnTaskDefinition` YAML files. +Separate examples are provided for each API version. +For example, the `lifecycle_v1alpha3_keptntaskdefinition` file +contains examples for the `v1alpha3` version of the lifecycle API group. + +## Files + +API Reference: + +* [KeptnTaskDefinition](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinition) +* [KeptnTaskDefinitionList](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionlist) +* [KeptnTaskDefinitionSpec](../crd-ref/lifecycle/v1alpha3/_index.md#keptntaskdefinitionspec) +* [FunctionReference](../crd-ref/lifecycle/v1alpha3/_index.md#functionreference) +* [FunctionSpec](../crd-ref/lifecycle/v1alpha3/_index.md#functionspec) +* [FunctionStatus](../crd-ref/lifecycle/v1alpha3/_index.md#functionstatus) +* [HttpReference](../crd-ref/lifecycle/v1alpha3/_index.md#httpreference) +* [Inline](../crd-ref/lifecycle/v1alpha3/_index.md#inline) + +## Differences between versions + +The `KeptnTaskDefinition` is the same for +all `v1alpha?` library versions. + +## See also + +* [Working with tasks](../implementing/tasks.md) +* Link to reference pages for any related CRDs