docs: add KeptnTask ref page; enhance guide chapter for keptn-no-k8s (k…

…eptn#2103) Signed-off-by: Meg McRoberts <[email protected]> Co-authored-by: RealAnna <[email protected]> Co-authored-by: odubajDT <[email protected]>
StackScribe · Oct 18, 2023 · 066be3e · 066be3e
1 parent 66e86c0
commit 066be3e
Show file tree

Hide file tree

Showing 2 changed files with 208 additions and 24 deletions.
diff --git a/docs/content/en/docs/implementing/tasks-non-k8s-apps.md b/docs/content/en/docs/implementing/tasks-non-k8s-apps.md
@@ -2,23 +2,43 @@
 title: Keptn for Non-Kubernetes Applications
 description: Using Keptn with Non-Kubernetes Applications
 weight: 95
-hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
 ---
 
-It is possible to trigger Keptn Tasks for workloads and applications that are deployed outside of Kubernetes.
+Keptn Tasks can be triggered for workloads and applications
+that are deployed outside of Kubernetes.
+For example, Keptn could trigger load and performance tests
+for an application that is deployed on a virtual machine.
 
-For example, to trigger a load test for an application deployed on a virtual machine.
+To do this:
 
-You will still need to deploy Keptn on a Kubernetes cluster, but this can be a very lightweight, single-node kind cluster.
-Keptn's only job is to trigger on-demand tasks, so resource utilization will be minimal.
+1. [Install and enable a Kubernetes cluster](#install-and-enable-a-kubernetes-cluster)
+1. [Create a KeptnTaskDefinition](#create-a-keptntaskdefinition)
+1. [Create and apply a KeptnTask](#create-and-apply-a-keptntask)
+1. [Re-run the KeptnTask](#re-run-the-keptntask)
 
-## Step 1: Create a KeptnTaskDefinition
+## Install and enable a Kubernetes cluster
 
-When you have Keptn installed, [create a KeptnTaskDefinition](../implementing/tasks/).
+You must still
+[install](../install/install.md/#use-helm-chart)
+Keptn on a Kubernetes cluster,
+but this can be a very lightweight, single-node KinD cluster; see
+[Create local Kubernetes cluster](../install/k8s.md/#create-local-kubernetes-cluster).
+Keptn only triggers on-demand `KeptnTask` resources
+so resource utilization is minimal.
 
-A `KeptnTaskDefinition` defines **what** you want to execute.
+## Create a KeptnTaskDefinition
 
-For example:
+When you have Keptn installed, create a
+YAML file that defines what you want to execute
+as a `KeptnTaskDefinition` resource..
+See
+[Deployment tasks](../implementing/tasks/)
+and the
+[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md/)
+reference page for more information.
+
+For example, you might create a `test-task-definition.yaml` file
+with the following content:
 
 ```yaml
 apiVersion: lifecycle.keptn.sh/v1alpha3
@@ -35,15 +55,27 @@ spec:
       - 'hello world'
 ```
 
-## Step 2: Create a KeptnTask for each run
+This example uses the `container-runtime` runner,
+but you can instead use the `deno-runtime` or `python-runtime` runner.
+See
+[Runners and containers](tasks/#runners-and-containers)
+for more information.
 
-Each time you want to execute a `KeptnTaskDefinition`, a new (and uniquely named) `KeptnTask` must be created.
+## Create and apply a KeptnTask
 
-In the standard operating mode, when Keptn is managing workloads, the creation of the `KeptnTask` CR is automatic.
+You must manually create the
+[KeptnTask](../yaml-crd-ref/task.md) resource.
+In the standard operating mode, when Keptn is managing workloads,
+the creation of the `KeptnTask` resource is automatic.
 
-Here though, we must create it ourselves.
+Moreover, each time you want to execute a `KeptnTask`,
+you must manually create a a new (and uniquely named) `KeptnTask` resource.
 
-The `KeptnTask` references the `KeptnTaskDefinition` in the `spec.taskDefinition` field:
+The `KeptnTask` resource references the `KeptnTaskDefinition`
+that you created above
+in the `spec.taskDefinition` field.
+For example, you might create a `test-task.yaml` file
+with the following content:
 
 ```yaml
 apiVersion: lifecycle.keptn.sh/v1alpha3
@@ -61,21 +93,33 @@ spec:
     workloadVersion: "1.0.0"
 ```
 
-Applying this file will cause Keptn to create a Job and a Pod and run the `KeptnTaskDefinition`.
+You can then apply this YAML file with the following command:
+
+```shell
+kubectl apply -f test-task.yaml -n my-keptn-annotated-namespace
+```
+
+Applying this file causes Keptn to create a Job and a Pod
+and run the executables defined
+in the associated `KeptnTaskDefinition` resource.
 
-`kubectl get keptntasks` and `kubectl get pods` will show the current status of the jobs.
+Use the following commands to show the current status of the jobs:
 
-## Running More KeptnTasks
+```shell
+kubectl get keptntasks -n my-keptn-annotated-namespace
+kubectl get pods -n my-keptn-annotated-namespace
+```
 
-For subsequent KeptnTask runs, the `KeptnTask` name needs to be unique, update the follow fields:
+## Re-run the KeptnTask
 
-- `name`
-- `spec.appVersion`
-- `spec.workloadVersion`
-- `spec.context.appVersion`
-- `spec.context.workloadVersion`
+For subsequent KeptnTask runs,
+the `KeptnTask` name and version fields must be unique,
+so copy the `KeptnTask` yaml file you have and update the
+`metadata.name` field.
 
-For example:
+A standard practice is to just increment the value of the suffix field.
+For example, you could create a `test-task-2.yaml` file
+with the `metadata.name` field set to `runhelloworld2`:
 
 ```yaml
 apiVersion: lifecycle.keptn.sh/v1alpha3
@@ -92,3 +136,9 @@ spec:
     workloadName: "my-workload"
     workloadVersion: "1.0.1"
 ```
+
+You can then apply this file with the following command:
+
+```shell
+kubectl apply -f test-task-2.yaml -n my-keptn-annotated-namespace
+```
diff --git a/docs/content/en/docs/yaml-crd-ref/task.md b/docs/content/en/docs/yaml-crd-ref/task.md
@@ -0,0 +1,134 @@
+---
+title: KeptnTask
+description: Define a run of a KeptnTaskDefinition
+weight: 85
+---
+
+When using Keptn to run tasks for software
+that is deployed outside of Kubernetes,
+you must create the `KeptnTask` resource manually
+and modify it manually for each new run.
+Keptn automatically populates the `KeptnTask` resource
+for tasks that deploy software on Kubernetes.
+
+## Synopsis
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTask
+metadata:
+  name: <name-of-this-run>
+spec:
+  taskDefinition: <name-of-KeptnTaskDefinition resource>
+  context:
+    appName: "<name-of-KeptnApp-resource>"
+    appVersion: "1.0.0"
+    objectType: ""
+    taskType: ""
+    workloadName: "my-workload"
+    workloadVersion: "1.0.0"
+  parameters: <parameters to pass to job>
+  secureParameters: <secure parameters to pass to job>
+  checkType: ""
+  retries: <integer>
+  timeout: <duration-in-seconds>
+```
+
+## Fields
+
+* **apiVersion** -- API version being used.
+`
+* **kind** -- Resource type.
+   Must be set to `KeptnTask`
+
+* **metadata**
+  * **name** -- Unique name of this run of the task.
+    This name must be modified each time you run this `KeptnTask`,
+    so a common practice is to add a number to the end of the string
+    so you can increment the number for each run.
+    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** - Defines the speficication of this `KeptnTask` resource
+  * **taskDefinition** - Name of the corresponding `KeptnTaskDefinition` resource.
+    This `KeptnTaskDefinition` can be located in the same namespace
+    or in the Keptn installation namespace.
+  * **context** - Contextual information about the task execution
+    * **appName** - Name of the
+      [KeptnApp](../yaml-crd-ref/app.md) resource
+      for which the `KeptnTask` is being executed.
+    * **appVersion** - Version of the `KeptnApp` resource
+      for which the `KeptnTask` is being executed.
+
+    * **objectType** - Indicates whether this `KeptnTask`
+      is being executed for a `KeptnApp` or a `KeptnWorkload` resource.
+      When populating this resource manually
+      to run a task for a non-Kubernetes deployment,
+      set this value to `""`:
+      Keptn populates this field based on annotations
+      to the `KeptnWorkload` and `KeptnApp` resources.
+
+    * **taskType** Indicates whether this `KeptnTask`
+      is part of the pre- or post-deployment phase.
+      When populating this resource manually
+      to run a task for a non-Kubernetes deployment,
+      set this value to `""`:
+      Keptn populates this field based on annotations
+      to the `KeptnWorkload` and `KeptnApp` resources.
+
+    * **workloadName** - Name of the `KeptnWorkload`
+      for which the `KeptnTask` is being executed.
+    * **workloadVersion** - Version of the `KeptnWorkload`
+      for which the `KeptnTask` is being executed.
+  * **parameters** (optional) -- Parameters that are passed to the job
+    that executes the `KeptnTask`.
+  * **secureParameters** (optional) -- Secure parameters that are passed
+    to the job that executes the `KeptnTask`.
+    These are stored and accessed as Kubernetes `Secrets` in the cluster.
+    See [Working with secrets](../implementing/tasks/#working-with-secrets)
+    for more information.
+  * **checkType** -- Defines whether task is part of pre- or post-deployment phase.
+    Keptn populates this field based on annotations
+    to the `KeptnWorkload` and `KeptnApp` resources.
+  * **retries** (optional) -- If errors occur,
+    this defines the number of attempts made
+    before the `KeptnTask` is considered to be failed.
+  * **timeout** (optional) -- Specifies the time, in seconds,
+    to wait for the `KeptnTask` to complete successfully.
+    If the `KeptnTask` does not complete successfully in this timeframe,
+    it is considered to be failed.
+
+## Usage
+
+Applying this file causes Keptn to create a Job and a Pod
+and run the associated `KeptnTaskDefinition`.
+
+Use the following commands to show the current status of the jobs:
+
+```shell
+kubectl get keptntasks
+kubectl get pods
+```
+
+Each time you want to rerun the `KeptnTask` resource,
+you must update the value of the `metadata.name` field.
+A common practice is to just increment the value incrementally,
+so `helloworldtask-1` becomes `helloworldtask-2`, etc.
+
+For a full example of how to create a `KeptnTask` resource
+to use for a deployment being done outside of Kubernetes, see
+[Keptn for Non-Kubernetes Applications](../implementing/tasks-non-k8s-apps.md).
+
+## Files
+
+[API reference](../crd-ref/lifecycle/v1alpha3/#keptntaskspec)
+
+## Differences between versions
+
+The syntax of the `KeptnTask` resource changed significantly
+in Keptn v0.8.0.
+
+## See also
+
+* [KeptnTaskDefinition](taskdefinition.md)
+* [Keptn for Non-Kubernetes Applications](../implementing/tasks-non-k8s-apps.md)