From 066be3e70bad96256a422c73af08a9384213c4e1 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 18 Oct 2023 00:59:27 -0700 Subject: [PATCH] docs: add KeptnTask ref page; enhance guide chapter for keptn-no-k8s (#2103) Signed-off-by: Meg McRoberts Co-authored-by: RealAnna <89971034+RealAnna@users.noreply.github.com> Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> --- .../docs/implementing/tasks-non-k8s-apps.md | 98 +++++++++---- docs/content/en/docs/yaml-crd-ref/task.md | 134 ++++++++++++++++++ 2 files changed, 208 insertions(+), 24 deletions(-) create mode 100644 docs/content/en/docs/yaml-crd-ref/task.md diff --git a/docs/content/en/docs/implementing/tasks-non-k8s-apps.md b/docs/content/en/docs/implementing/tasks-non-k8s-apps.md index 98b18e4e01..4337150611 100644 --- 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 new file mode 100644 index 0000000000..ced30b39fd --- /dev/null +++ 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: +spec: + taskDefinition: + context: + appName: "" + appVersion: "1.0.0" + objectType: "" + taskType: "" + workloadName: "my-workload" + workloadVersion: "1.0.0" + parameters: + secureParameters: + checkType: "" + retries: + timeout: +``` + +## 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)