From 3834b709da4552a07c8acd8699d1e8a583a621bd Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 20 Jun 2023 02:55:55 -0700 Subject: [PATCH] docs: document container-runtime and python-runtime runners (#1579) Signed-off-by: Meg McRoberts Signed-off-by: Giovanni Liva Signed-off-by: RealAnna <89971034+RealAnna@users.noreply.github.com> Co-authored-by: Giovanni Liva Co-authored-by: RealAnna <89971034+RealAnna@users.noreply.github.com> --- .../getting-started/orchestrate/_index.md | 9 +- .../en/docs/implementing/integrate/_index.md | 2 +- .../en/docs/implementing/tasks/_index.md | 83 +++- docs/content/en/docs/yaml-crd-ref/app.md | 70 +-- .../en/docs/yaml-crd-ref/taskdefinition.md | 415 ++++++++++++++++-- 5 files changed, 507 insertions(+), 72 deletions(-) diff --git a/docs/content/en/docs/getting-started/orchestrate/_index.md b/docs/content/en/docs/getting-started/orchestrate/_index.md index c4ebafb1fa..5251b43ee9 100644 --- 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 index d674ecd612..0bae8753a7 100644 --- 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 index d896143eee..ba2351ed6a 100644 --- 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 index e4d0d790d0..be3cc41e0a 100644 --- 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) diff --git a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md index dc2a2bd2c3..002617f477 100644 --- a/docs/content/en/docs/yaml-crd-ref/taskdefinition.md +++ b/docs/content/en/docs/yaml-crd-ref/taskdefinition.md @@ -4,14 +4,57 @@ 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](./app.md) or [KeptnWorkload](../concepts/workloads/). -## Yaml Synopsis +A Keptn task executes as a +[runner](https://docs.gitlab.com/runner/executors/kubernetes.html#how-the-runner-creates-kubernetes-pods) +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/). + +Each `KeptnTaskDefinition` can use exactly one container with one runner. +which is one of the following, +differentiated by the `spec` section: + +* The `custom-runtime` runner provides + a standard Kubernetes application container + that is run as part of a Kubernetes job.. + You define the runner, an application, + and its runtime dependencies. + This gives you the flexibility + to define tasks using the lanugage and facilities of your choice, + although it is more complicated that using one of the pre-defined runtimes. + See + [Yaml synopsis for container-runtime](#yaml-synopsis-for-container-runtime) + and + [Examples for a custom-runtime container](#examples-for-a-custom-runtime-container). +* Use the pre-defined `deno-runtime` runner + to define tasks using Deno scripts, + which use a syntax similar to JavaScript and Typescript, + with a few limitations. + You can use this to specify simple actions + without having to define a container. + See + [Yaml synopsis for Deno-runtime container](#yaml-synopsis-for-deno-runtime-container) + and + [Deno-runtime examples](#examples-for-deno-runtime-runner). +* Use the pre-defined `python-runtime` runner + to define your task using Python 3. + See + [Yaml synopsis for python-runtime runner](#yaml-synopsis-for-python-runtime-runner) + and + [Examples for a python-runtime runner](#examples-for-a-python-runtime-runner). + +## Yaml Synopsis for all runners + +The `KeptnTaskDefinition` Yaml files for all runners +include the same lines at the top. +These are described here. ```yaml apiVersion: lifecycle.keptn.sh/v?alpha? @@ -19,16 +62,18 @@ kind: KeptnTaskDefinition metadata: name: spec: - function: - inline | httpRef | functionRef | ConfigMapRef - parameters: - map: - textMessage: "This is my configuration" - secureParameters: - secret: slack-token + function | python | container + ... + retries: + timeout: ``` -## Fields +The API ref points to +[Kubernetes doc](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#duration-v1-meta) +where I don't find a direct hit +but timeouts seem to be measured in seconds. + +### Fields used for all containers * **apiVersion** -- API version being used. ` @@ -36,16 +81,77 @@ spec: Must be set to `KeptnTaskDefinition` * **metadata** - * **name** -- Unique name of this task. + * **name** -- Unique name of this task or container. + This is the name used to insert this task or container + into the `preDeployment` or `postDeployment` list. 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** + * **function | python | container** -- Define the container type + to use for this task. + Each task can use one type of runner, + identified by this field: + * **function** -- Use a `deno-runtime` runner + and code the functionality in Deno script, + which is similar to JavaScript and Typescript. + See + [Yaml synopsis for deno-runtime contailer](#yaml-synopsis-for-deno-runtime-container). + * **python** -- Use a `python-runtime` function + and code the functionality in Python 3. + See + [Yaml synopsis for python-runtime runner](#yaml-synopsis-for-python-runtime-runner) + * **container** -- Use the runner defined + for the `container-runtime` container. + This is a standard Kubernetes container + for which you define the image, runner, runtime parameters, etc. + and code the functionality to match the container you define. + See + [Yaml synopsis for container-runtime contaier](#yaml-synopsis-for-container-runtime). + * **retries** (optional) - specifies the number of times, + a job executing the `KeptnTaskDefinition` + should be restarted if an attempt is unsuccessful. + * **timeout** (optional)* -- specifies the maximum time, in seconds, + to wait for the task to be completed successfully. + If the task does not complete successfully within this time frame, + it is considered to be failed. + +## Yaml Synopsis for deno-runtime container + +When using the `deno-runtime` runner to define a task, +the `function` is coded in Deno-script +(which is mostly the same as JavaScript and TypeScript) +and executed in the +[Deno](https://deno.com/runtime) runner, +which is a lightweight runtime environment +that executes in your namespace. +Note that Deno has tighter restrictions +for permissions and importing data +so a script that works properly elsewhere +may not function out of the box when run in the `deno-runtime` runner. + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnTaskDefinition +metadata: + name: +spec: + function: + inline | httpRef | functionRef | ConfigMapRef + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +### Spec fields for deno-runtime definitions * **spec** * **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. + for more information about this runner. The `function` can be defined as one of the following: @@ -74,7 +180,7 @@ spec: ``` * **functionRef** -- Execute one or more `KeptnTaskDefinition` resources - that have been defined. + that have been defined to use the `deno-runtime` runner. Populate this field with the value(s) of the `name` field for the `KeptnTaskDefinition`(s) to be called. This is commonly used to call a general function @@ -130,37 +236,192 @@ spec: See [Create secret text](../implementing/tasks/#create-secret-text) for details. +## Yaml Synopsis for container-runtime + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnTaskDefinition +metadata: + name: +spec: + container: + name: + image: + +``` + +### Spec used only for container-runtime + +The `container-runtime` can be used to specify +your own container image and define almost task you want to do. +If you are migrating from Keptn v1, +you can use a `container-runtime` to execute +almost anything that you implemented with JES for Keptn v1. + +* **spec** + * **container** -- Container definition. + * **name** -- Name of the container that will run, + which is not the same as the `metadata.name` field + that is used in the `KeptnApp` resource. + * **image** -- name of the image you defined according to + [image reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#image) + and + [image concepts](https://kubernetes.io/docs/concepts/containers/images/) + and pushed to a registry + * **other fields** -- The full list of valid fields is available at + [ContainerSpec](../crd-ref/lifecycle/v1alpha3/#containerspec), + with additional information in the Kubernetes + [Container](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container) + spec documentation. + +## Yaml Synopsis for Python-runtime runner + +The `python-runtime` runner is built on the `container-runtime` runner +to provide a way easily define a task using Python 3. +You do not need to specify the image, volumes, and so forth. +Instead, just provide a Python script +and KLT sets up the container and runs the script as part of the task. + +```yaml +apiVersion: lifecycle.keptn.sh/v?alpha? +kind: KeptnTaskDefinition +metadata: + name: +spec: + python: + inline | httpRef | functionRef | ConfigMapRef + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +### Spec used only for the python-runtime runner + +The `python-runtime` runner is used to define tasks using Python 3 code. + +* **spec** + * **python** -- Identifies this as a Python runner. + * **inline** -- Include the actual Python 3.1 code to execute. + For example, the following example + prints data stored in the parameters map: + + ```yaml + python: + inline: + code: | + data = os.getenv('DATA') + print(data) + ``` + + * **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: + python: + httpRef: + url: "https://www.example.com/yourscript.py" + ``` + + * **functionRef** -- Execute one or more `KeptnTaskDefinition` resources + that have been defined to use the `python-runtime` runner. + Populate this field with the value(s) of the `metadata.name` field + for each `KeptnDefinitionTask` 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: + python: + functionRef: + name: slack-notification + ``` + + This can also be used to group a set of tasks + into a single `KeptnTaskDefinition`, + such as defining a `KeptnTaskDefinition` for testing. + In this case, it calls other, existing `KeptnTaskDefinition`s + for each type of test to be run, + specifying each by the value of the `name` field. + + * **ConfigMapRef** -- Specify the name of a + [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) + resource that contains the function to be executed. + + * **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: + + ```yaml + spec: + parameters: + map: + textMessage: "This is my configuration" + ``` + + See + [Parameterized functions](../implementing/tasks/#parameterized-functions) + for more information. + + * **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 + ``` + + Note that, currently, only one secret can be passed. + + See [Create secret text](../implementing/tasks/#create-secret-text) + for details. + ## Usage A Task executes the TaskDefinition of a -[KeptnApp](app.md) or [KeptnWorkload]. +[KeptnApp](app.md) or a +[KeptnWorkload](../concepts/workloads). The execution is done by spawning a Kubernetes [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) to handle a single Task. In its state, it tracks the current status of this Kubernetes Job. -The `function` is coded in JavaScript -and executed in -[Deno](https://deno.com/runtime), -which is a lightweight runtime environment -that executes in your namespace. -Note that Deno has tighter restrictions -for permissions and importing data -so a script that works properly elsewhere -may not function out of the box when run in Deno. +When using a container runtime that includes a volume, +an `EmptyDir` volume is created +with the same name as is specified the container `volumeMount`. +Note that, if more `volumeMount`s are specified, +only one volume is created with the name of the first `volumeMount`. +By default, the size of this volume is 1GB. +If the memory limit for the container is set, +the size of the volume is 50% of the memory allocated for the node. A task can be executed either pre-deployment or post-deployment -as specified in the `Deployment` resource; -see +as specified in the pod template specs of your Workloads +([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), +and +[ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/). +See [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks) for details. Note that the annotation identifies the task by `name`. This means that you can modify the `function` code in the resource definition and the revised code is picked up without additional changes. -## Examples +## Examples for deno-runtime runner -### Example 1: inline script +### Example 1: inline script for a Deno script This example defines a full-fledged Deno script within the `KeptnTaskDefinition` YAML file: @@ -183,7 +444,7 @@ spec: console.log("Hello, " + name + " new"); ``` -### Example 2: httpRef script +### Example 2: httpRef script for a Deno script This example fetches the Deno script from a remote webserver at runtime: @@ -205,7 +466,7 @@ 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: functionRef +### Example 3: functionRef for a Deno script This example calls another defined task, illustrating how one `KeptnTaskDefinition` can build @@ -229,7 +490,7 @@ spec: secret: slack-token ``` -### Example 4: ConfigMapRef +### Example 4: ConfigMapRef for a Deno script This example references a `ConfigMap` by the name of `dev-configmap` that contains the code for the function to be executed. @@ -245,7 +506,7 @@ spec: name: dev-configmap ``` -### Example 5: ConfigMap +### Example 5: ConfigMap for a Deno script This example illustrates the use of both a `ConfigMapRef` and a `ConfigMap`: @@ -282,7 +543,78 @@ data: console.log(targetDate); ``` -### More examples +## Examples for a custom-runtime container + +For an example of a `KeptnTaskDefinition` that defines a custom container. + see +[container-task.yaml](. +The `spec` includes: + +```yaml +spec: + container: + name: testy-test + image: busybox:1.36.0 + command: + - 'sh' + - '-c' + - 'sleep 30' +``` + +This task is then referenced in + +[app.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/sample-app/version-3/app.yaml). + +This is a a trivial example that just runs `busybox`, +then spawns a shell and runs the `sleep 30` command. + +## Examples for a python-runtime runner + +### Example 1: inline code for a python-runtime runner + +You can embed python code directly in the task definition. +This example prints data stored in the parameters map: +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_inline.yaml" >}} + +### Example 2: httpRef for a python-runtime runner + +You can refer to code stored online. +For example, we have a few examples available in the +[python-runtime samples](https://github.com/keptn/lifecycle-toolkit/tree/main/python-runtime/samples) +tree. + +Consider the following: +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_configmap.yaml" >}} + +### Example 3: functionRef for a python-runtime runner + +You can refer to an existing `KeptnTaskDefinition`. +This example calls the inline example +but overrides the data printed with what is specified in the task: +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_recursive.yaml" >}} + +### Example 4: ConfigMapRef for a python-runtime runner + +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_configmap.yaml" >}} + +### Allowed libraries for the python-runtime runner + +The following example shows how to use some of the allowed packages, namely: +requests, json, git, and yaml: + +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_inline_printargs_py.yaml">}} + +### Passing secrets, environment variables and modifying the python command + +The following examples show how to pass data inside the parameter map, +how to load a secret in your code, +and how to modify the python command. +In this case the container runs with the `-h` option, +which prints the help message for the python3 interpreter: + +{{< embed path="/operator/config/samples/python_execution/taskdefinition_pyfunction_use_envvars.yaml" >}} + +## More examples See the [operator/config/samples](https://github.com/keptn/lifecycle-toolkit/tree/main/operator/config/samples/function_execution) directory for more example `KeptnTaskDefinition` YAML files. @@ -302,11 +634,26 @@ API Reference: ## Differences between versions -The `KeptnTaskDefinition` is the same for -all `v1alpha?` library versions. +The `KeptnTaskDefinition` support for +the `container-runtime` and `python-runtime` is introduced in v0.8.0. +This modifies the synopsis in two ways: + +* Add the `spec.container` field. +* The `spec.function` field is changed to be a pointer receiver. + This aligns it with the `spec.container` field, + which must be a pointer, + and enables `KeptnTask` to omit it when it is empty, + which it must be when `spec.container` is populated. + +## Limitations + +Only one +[runtime](https://kubernetes.io/docs/setup/production-environment/container-runtimes/) +is allowed per `KeptnTaskDefinition`. ## See also +* [KeptnApp](app.md) * [Working with tasks](../implementing/tasks) * [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks) * [Orchestrate deployment checks](../getting-started/orchestrate)