docs: document container-runtime and python-runtime runners (keptn#1579)

Signed-off-by: Meg McRoberts <[email protected]> Signed-off-by: Giovanni Liva <[email protected]> Signed-off-by: RealAnna <[email protected]> Co-authored-by: Giovanni Liva <[email protected]> Co-authored-by: RealAnna <[email protected]>
StackScribe · Jun 20, 2023 · 3834b70 · 3834b70
1 parent 2e53fda
commit 3834b70
Show file tree

Hide file tree

Showing 5 changed files with 507 additions and 72 deletions.
diff --git a/docs/content/en/docs/getting-started/orchestrate/_index.md b/docs/content/en/docs/getting-started/orchestrate/_index.md
@@ -134,7 +134,7 @@ Tasks are resources that are defined in a
 file.
 In our example, the tasks are defined in the
 [keptn-tasks.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-tasks.yaml)
-file
+file.
 As an example,
 we have a `notify` task that composes some markdown text
 to be sent as Slack notifications
@@ -165,6 +165,13 @@ For this example, the code to be executed is embedded in this file
 although, in practice,
 this script would probably be located on a remote webserver.
 
+Note that, beginning with KLT 0.8.0,
+you can also use Python 3 to define your task,
+or you can define a standard Kubernetes container
+that uses the image, runner, and runtime dependencies that you choose.
+For more information, see
+[Working with Keptn tasks](../../implementing/tasks).
+
 You can view the actual JavaScript code for the task in the repository.
 You see that "context" is important in this code.
 This refers to the context in which this code executes --

diff --git a/docs/content/en/docs/implementing/integrate/_index.md b/docs/content/en/docs/implementing/integrate/_index.md
@@ -51,7 +51,7 @@ and
 and
 [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/)
 in the namespaces where KLT is enabled.
-If KLT finds any of hese resources and the resource has either
+If KLT finds any of these resources and the resource has either
 the keptn.sh or the kubernetes recommended labels,
 it creates a `KeptnWorkload` resource for the version it detects.
 

diff --git a/docs/content/en/docs/implementing/tasks/_index.md b/docs/content/en/docs/implementing/tasks/_index.md
@@ -5,12 +5,70 @@ weight: 90
 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
 ---
 
-Keptn tasks are defined in a
+A
 [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md/)
-resource.
-A task definition includes a function
+resource defines tasks that the Keptn Lifecycle Toolkit runs
+as part of the pre- and post-deployment phases of a
+[KeptnApp](../../yaml-crd-ref/app.md) or
+[KeptnWorkload](../../concepts/workloads).
+
+A Keptn task executes as a runner in an application
+[container](https://kubernetes.io/docs/concepts/containers/),
+which runs as part of a Kubernetes
+[job](https://kubernetes.io/docs/concepts/workloads/controllers/job/).
+A `KeptnTaskDefinition` includes a function
 that defines the action taken by that task.
-It can be configured in one of three different ways:
+
+To implement a Keptn task:
+
+- Define a
+  [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md)
+  resource that defines the runner to use for the container
+- [Annotate your workloads](../integrate/#annotate-workloads)
+  to integrate your task with Kubernetes
+- Add your task to the [KeptnApp](../../yaml-crd-ref/app.md)
+  resource that associates your `KeptnTaskDefinition`
+  with the pre- and post-deployment tasks that should run in it
+
+This page provides information to help you create your tasks:
+
+- Code your task in an appropriate [runner](#runners-and-containers)
+- Understand how to use [Context](#context)
+  that contains a Kubernetes cluster, a user, a namespace,
+  the application name, workload name, and version.
+- Use [parameterized functions](#parameterized-functions)
+  if your task requires input parameters
+- [Create secret text](#create-secret-text)
+  and [pass secrets to a function](#pass-secrets-to-a-function)
+  if necessary.
+
+## Runners and containers
+
+Each `KeptnTaskDefinition` can use exactly one container with one runner.
+The runner you use determines the language you can use
+to define the task.
+The `spec` section of the `KeptnTaskDefinition`
+defines the runner to use for the container:
+
+- The `container-runtime` runner provides
+  a pure custom Kubernetes application container
+  that you define to includes a runtime, an application
+  and its runtime dependencies.
+  This gives you the greatest flexibility
+  to define tasks using the lanugage and facilities of your choice
+
+KLT also includes two "pre-defined" runners:
+
+- Use the `deno-runtime` runner to define tasks using Deno scripts,
+  which use JavaScript/Typescript syntax with a few limitations.
+  You can use this to specify simple actions
+  without having to define a container.
+- Use the `python-runtime` runner
+  to define your task using Python 3.
+
+For the pre-defined runners (`deno-runtime` and `python-runtime`),
+the actual code to be executed
+can be configured in one of four different ways:
 
 - inline
 - referring to an HTTP script
@@ -19,7 +77,11 @@ It can be configured in one of three different ways:
   [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/)
   resource that is populated with the function to execute
 
-### Context
+See the
+[KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md)
+reference page for the synopsis and examples for each runner.
+
+## Context
 
 A Kubernetes context is a set of access parameters
 that contains a Kubernetes cluster, a user, a namespace,
@@ -88,7 +150,13 @@ Note the following about using parameters with functions:
   The secret must have a `key` called `SECURE_DATA`.
   It can be accessed via the environment variable `Deno.env.get("SECURE_DATA")`.
 
-## Create secret text
+## Working with secrets
+
+A special case of parameterized functions
+is to pass secrets that may be required
+to access data that your task requires.
+
+### Create secret text
 
 To create a secret to use in a `KeptnTaskDefinition`,
 execute this command:
@@ -139,9 +207,8 @@ spec:
         // secret_text_obj["foo2"] = "bar2"
 ```
 
-## Pass secrets to a function
+### Pass 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

diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/yaml-crd-ref/app.md
@@ -6,10 +6,16 @@ weight: 10
 
 `KeptnApp` defines a list of workloads
 that together constitute a logical application.
-It contains information about all workloads and checks
-that are associated with a Keptn application
-and a list of tasks and evaluations to be executed
-pre- and post-deployment.
+It contains information about:
+
+- All workloads and checks
+  that are associated with a Keptn application
+- A list of tasks and evaluations to be executed
+  pre- and post-deployment.
+- Tasks referenced by `KeptnApp` are defined in a
+  [KeptnTaskDefinition](taskdefinition.md) resource.
+  `KeptnApp` identifies the task by the value of the `metadata.name` field
+  and does not need to understand what runner is used to define the task.
 
 ## Synopsis
 
@@ -39,51 +45,53 @@ spec:
 
 ## Fields
 
-* **apiVersion** -- API version being used.
-* **kind** -- Resource type.
+- **apiVersion** -- API version being used.
+- **kind** -- Resource type.
    Must be set to `KeptnApp`
 
-* **metadata**
-  * **name** -- Unique name of this application.
+- **metadata**
+  - **name** -- Unique name of this application.
     Names must comply with the
     [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names)
     specification.
 
-* **spec**
-  * **version** -- version of the Keptn application.
+- **spec**
+  - **version** -- version of the Keptn application.
     Changing this version number causes a new execution
     of all application-level checks
-  * **revision** -- revision of a `version`.
+  - **revision** -- revision of a `version`.
     The value is an integer that can be modified
     to trigger another deployment of a `KeptnApp` of the same version.
     For example, increment this number to restart a `KeptnApp` version
     that failed to deploy, perhaps because a
-    `preDeploymentEvaluation` or `preDeploymentTask` failed.
-  * **workloads**
-    * **name** - name of this Kubernetes
+    `preDeploymentEvaluation` or `preDeploymentTask` failed
+    for reasons that may be transient.
+  - **workloads**
+    - **name** - name of this Kubernetes
       [workload](https://kubernetes.io/docs/concepts/workloads/).
       Use the same naming rules listed above for the application name.
       Provide one entry for each workload
       associated with this Keptn application.
-    * **version** -- version number for this workload.
+    - **version** -- version number for this workload.
       Changing this number causes a new execution
-      of checks for the Keptn application and the new version of the workload.
-  * **preDeploymentTasks** -- list each task to be run
-    as part of the pre-deployment stage.
-    Task names must match the value of the `name` field
+      of checks for this workload only,
+      not the entire application.
+  - **preDeploymentTasks** -- list each task
+    to be run as part of the pre-deployment stage.
+    Task names must match the value of the `metadata.name` field
     for the associated [KeptnTaskDefinition](taskdefinition.md) resource.
-  * **postDeploymentTasks** -- list each task to be run
-    as part of the post-deployment stage.
-    Task names must match the value of the `name` field
+  - **postDeploymentTasks** -- list each task
+    to be run as part of the post-deployment stage.
+    Task names must match the value of the `metadata.name` field
     for the associated [KeptnTaskDefinition](taskdefinition.md) resource.
-  * **preDeploymentEvaluations** -- list each evaluation to be run
+  - **preDeploymentEvaluations** -- list each evaluation to be run
     as part of the pre-deployment stage.
-    Evaluation names must match the value of the `name` field
+    Evaluation names must match the value of the `metadata.name` field
     for the associated [KeptnEvaluationDefinition](evaluationdefinition.md)
     resource.
-  * **postDeploymentEvaluations** -- list each evaluation to be run
+  - **postDeploymentEvaluations** -- list each evaluation to be run
     as part of the post-deployment stage.
-    Evaluation names must match the value of the `name` field
+    Evaluation names must match the value of the `metadata.name` field
     for the associated [KeptnEvaluationDefinition](evaluationdefinition.md)
     resource.
 
@@ -107,7 +115,9 @@ based on Keptn or [recommended Kubernetes labels](https://kubernetes.io/docs/con
 This allows you to use the KLT observability features for existing resources
 without manually populating any Keptn related resources.
 
-## Example
+## Examples
+
+### Example
 
 ```yaml
 apiVersion: lifecycle.keptn.sh/v1alpha3
@@ -132,8 +142,12 @@ spec:
 
 ## Differences between versions
 
-The `spec.Revision` field is introduced in v1alpha2.
+- The `spec.revision` field is introduced in v1alpha2.
 
 ## See also
 
+- [KeptnTaskDefinition](taskdefinition.md)
+- [Working with tasks](../implementing/tasks)
+- [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks)
+- [Orchestrate deployment checks](../getting-started/orchestrate)
 [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery)