docs: reference page for KeptnTaskDefinition

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:

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

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"
+    }
+  ]
+}
+```

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);
+```

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)