docs: reference page for KeptnTaskDefinition

docs/content/en/docs/api-ref/_index.md

@@ -0,0 +1,29 @@
+---
+title: API Reference
+description: Reference information about the KLT CRDs
+weight: 100
+hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+This section provides comprehensive reference information about the
+[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+that are defined for the Keptn Lifecycle Toolkit.
+
+> **Note**
+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!**
+
+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.
+Keptn APIs follow API versioning conventions recommended by Kubernetes.
+
+For more information, see the Kubernetes documentation:
+
+* [API Overview](https://kubernetes.io/docs/reference/using-api/)
+* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
+* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)

docs/content/en/docs/api-ref/lifecycle/_index.md

@@ -0,0 +1,4 @@
+---
+title: Lifecycle API
+description: Reference information about the Lifecycle API
+---

docs/content/en/docs/crd-ref/TaskDefinition/index.md

@@ -0,0 +1,279 @@
+---
+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`.
+
+## Yaml Synopsis
+
+```yaml
+apiVersion: <lifecycle.keptn.sh/v?alpha?>
+kind: KeptnTaskDefinition
+metadata:
+  name: <task-name>
+spec:
+  function:
+    inline: | httpRef | functionRef
+    [parameters:
+      map:
+        textMessage: "This is my configuration"]
+    [secureParameters:
+      secret: slack-token]
+```
+
+## Fields
+
+* **apiVersion** -- API version being used.
+`
+* **kind** -- CRD 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 `_`, `-`, <what 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.
+  In the future, we intend to support additional runtimes,
+  especially running a container image directly.
+
+  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:
+
+    ```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: <url>
+    ```
+
+  * **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 `KeptnTaskDefinitions`,
+    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:
+
+   ```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.
+The execution is done by spawning a Kubernetes Job to handle a single Task.
+In its state, it tracks the current status of this Kubernetes Job.
+
+### Context
+
+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/v1alpha1
+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/v1alpha1
+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** defines a full-fletched Deno script
+within the `KeptnTaskDefinition` YAML file:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha2
+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** fetches the Deno script from a remote webserver at runtime:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha2
+kind: KeptnTaskDefinition
+metadata:
+  name: hello-keptn-http
+spec:
+  function:
+    httpRef:
+      url: <url>
+```
+
+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** 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/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
+```
+
+## Files
+
+API Reference:
+
+* [KeptnTaskDefinition](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinition)
+* [KeptnTaskDefinitionList](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionlist)
+* [KeptnTaskDefinitionSpec](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionspec)
+* [FunctionReference](../../api-ref/lifecycle/v1alpha3/#functionreference)
+* [FunctionSpec](../../api-ref/lifecycle/v1alpha3/#functionspec)
+* [FunctionStatus](../../api-ref/lifecycle/v1alpha3/#functionstatus)
+* [HttpReference](../../api-ref/lifecycle/v1alpha3/#httpreference)
+* [Inline](../../api-ref/lifecycle/v1alpha3/#inline)
+
+## Differences between versions
+
+The `KeptnTaskDefinition` is the same for
+all `v1alpha?` library versions.
+
+## See also
+
+* Link to "use-case" guide pages that do something interesting with this CRD
+* Link to reference pages for any related CRDs

docs/content/en/docs/crd-ref/_index.md

@@ -1,11 +1,12 @@
 ---
-title: API Reference
+title: CRD Reference
 description: Reference information about the KLT CRDs
-weight: 100
+weight: 200
 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
 ---
 
 This section provides comprehensive reference information about the
+YAML files that create the
 [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
 that are defined for the Keptn Lifecycle Toolkit.
 
@@ -15,7 +16,8 @@ Information that is published here has been reviewed for technical accuracy
 but the format and content is still evolving.
 We welcome your input!**
 
-Each CRD is an object of an API library.
+Each CRD is an object of an
+[API library](../../docs/api-ref/)
 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.

docs/content/en/docs/crd-ref/crd-template

@@ -0,0 +1,33 @@
+---
+title: <crd-template>
+description: <one-line description of CRD>
+weight: <assign weight to create alphabetical order>
+hidden: true
+---
+
+Copy this template to create a new CRD reference page.
+
+1. Replace the variable text in metadata with information for this page
+1. Delete the `hidden: true` line
+1. Delete these instructions from your file
+1. Populate the page with appropriate content
+
+## Synopsis
+
+## Fields
+
+<!-- Detailed description of each field-->
+
+## Usage
+
+<!-- How this CRD is "activated".  For example, which event uses this CRD -->
+<!-- Instructions and guidelines for when and how to customize a CRD -->
+
+## Examples
+
+## Files
+
+## Differences between versions
+
+## See also
+