Skip to content

Commit

Permalink
docs: add KeptnTask ref page; enhance guide chapter for keptn-no-k8s (#…
Browse files Browse the repository at this point in the history
…2103)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Co-authored-by: RealAnna <89971034+RealAnna@users.noreply.github.com>
Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>
  • Loading branch information
3 people committed Oct 18, 2023
1 parent 66e86c0 commit 066be3e
Show file tree
Hide file tree
Showing 2 changed files with 208 additions and 24 deletions.
98 changes: 74 additions & 24 deletions docs/content/en/docs/implementing/tasks-non-k8s-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
```
134 changes: 134 additions & 0 deletions docs/content/en/docs/yaml-crd-ref/task.md
Original file line number Diff line number Diff line change
@@ -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)

0 comments on commit 066be3e

Please sign in to comment.