runs.md

Runs

• Overview
• Configuring a Run
  • Specifying the target Custom Task
  • Specifying Parameters
  • Specifying Workspaces, Service Account, and Pod Template
• Monitoring execution status
  • Monitoring Results
• Code examples
  • Example Run with a referenced custom task
  • Example Run with an unnamed custom task
  • Example of specifying parameters

Overview

A Run allows you to instantiate and execute a Custom Task, which can be implemented by a custom task controller running on-cluster. Custom Tasks can implement behavior that doesn't correspond directly to running a workload in a Pod on the cluster. For Pod-based on-cluster workloads, you should use a TaskRun.

In order for a Run to actually execute, there must be a custom task controller running on the cluster that is responsible for watching and updating Runs which reference their type. If no such controller is running, Runs will have no .status value and no further action will be taken.

Runs are an experimental alpha feature and should be expected to change in breaking ways or even be removed.

Configuring a Run

A Run definition supports the following fields:

• Required:
  • apiVersion - Specifies the API version, for example tekton.dev/v1beta1.
  • kind - Identifies this resource object as a Run object.
  • metadata - Specifies the metadata that uniquely identifies the Run, such as a name.
  • spec - Specifies the configuration for the Run.
    • ref - Specifies the type and (optionally) name of the custom task type to execute.
    • spec - Embed the custom task resource spec directly in a Run.
• Optional:
  • params - Specifies the desired execution parameters for the custom task.
  • serviceAccountName - Specifies a ServiceAccount object that provides custom credentials for executing the Run.
  • workspaces - Specifies the physical volumes to use for the Workspaces required by a custom task.
  • podTemplate - Specifies a Pod template to use to configure pods created by the custom task.

Specifying the target Custom Task

A custom task resource's Spec may be directly embedded in the Run or it may be referred to by a Ref. But, not both at the same time.

1. Specifying the target Custom Task with ref Referring a custom task (i.e. Ref ) promotes reuse of custom task definitions.

2. Specifying the target Custom Task by embedding its spec Embedding a custom task (i.e. Spec ) helps in avoiding name collisions with other users within the same namespace. Additionally, in a pipeline with multiple embedded custom tasks, the details of entire pipeline can be fetched in a single API request.

1. Specifying the target Custom Task with ref

To specify the custom task type you want to execute in your Run, use the ref field as shown below:

spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example

This initiates the execution of a Run of a custom task of type Example, in the example.dev API group, with the version v1alpha1.

You can also specify the name and optional namespace (default is default) of a custom task resource object previously defined in the cluster.

spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example

If the ref specifies a name, the custom task controller should look up the Example resource with that name, and use that object to configure the execution.

If the ref does not specify a name, the custom task controller might support some default behavior for executing unnamed tasks.

In either case, if the named resource cannot be found, or if unnamed tasks are not supported, the custom task controller should update the Run's status to indicate the error.

2. Specifying the target Custom Task by embedding its spec

To specify the custom task spec, it can be embedded directly into a Run's spec as shown below:

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: embedded-run
spec:
  spec:
    apiVersion: example.dev/v1alpha1
    kind: Example
    spec:
      field1: value1
      field2: value2

This initiates the execution of a Run of a custom task of type Example, in the example.dev API group, with the version v1alpha1.

Developer guide for custom controllers supporting spec.

1. A custom controller may or may not support a Spec. In cases where it is not supported the custom controller should respond with proper validation error.

2. Validation of the fields of the custom task is delegated to the custom task controller. It is recommended to implement validations as asynchronous (i.e. at reconcile time), rather than part of the webhook. Using a webhook for validation is problematic because, it is not possible to filter custom task resource objects before validation step, as a result each custom task resource has to undergo validation by all the installed custom task controllers.

3. A custom task may have an empty spec, but cannot have an empty ApiVersion and Kind. Custom task controllers should handle an empty spec, either with a default behaviour, in a case no default behaviour is supported then, appropriate validation error should be updated to the Run's status.

Specifying Timeout

A custom task specification can be created with Timeout as follows:

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  generateName: simpleexample
spec:
  timeout: 10s # set timeouts here.
  params:
    - name: searching
      value: the purpose of my existence
  ref:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName

Supporting timeouts is optional but recommended.

Developer guide for custom controllers supporting Timeout

1. Tekton controllers will never directly update the status of the Run, it is the responsibility of the custom task controller to support timeout. If timeouts are not supported, it's the responsibility of the custom task controller to reject Runs that specify a timeout value.
2. On a pipelineRun or pipelineTask timeout, the status of the Run.Spec.Status is updated to RunCancelled. It is up to the custom task controller to respond to it. An existing controller, which does not yet support timeout, will be able to cleanup, if it supports a cancel.
3. A Custom Task author can watch for this status update (i.e. Run.Spec.Status == RunCancelled) and or Run.HasTimedOut() and take any corresponding actions (i.e. a clean up e.g., cancel a cloud build, stop the waiting timer, tear down the approval listener).
4. A Custom Task author can differentiate between a Run cancelled by an user from a Run cancellation initiated by a PipelineRun by looking at the Run.Spec.StatusMessage. If a Run cancellation has been initiated by a cancellation of a PipelineRun then Run.Spec.StatusMessage is "Run cancelled as the PipelineRun it belongs to has been cancelled.".
5. Once resources or timers are cleaned up it is good practice to set a conditions on the Run's status of Succeeded/False with a Reason of RunTimedOut.

Specifying Retries

A custom task specification can be created with Retries as follows:

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  generateName: simpleexample
spec:
  retries: 3 # set retries
  params:
    - name: searching
      value: the purpose of my existence
  ref:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName

Supporting retries is optional but recommended.

Developer guide for custom controllers supporting retries

1. Tekton controllers will use the entire timeout duration for exhausting all the retries the custom task is configured to run with. In other words, tekton does not discriminate, if the failure was due to a stuck up process or exhausting all the retries. Custom task developers are recommended to use the same strategy for implementing their timeout for the custom task.
2. Those custom task who do not wish to support retry, can simply ignore it.
3. It is recommended, that custom task should update the field RetriesStatus of a Run on each retry performed by the custom task.
4. Tekton controller does not validate that number of entries in RetriesStatus is same as specified value of retries count.

Specifying Parameters

If a custom task supports parameters, you can use the params field in the Run to specify their values:

spec:
  params:
    - name: my-param
      value: chicken

If the custom task controller knows how to interpret the parameter value, it will do so. It might enforce that some parameter values must be specified, or reject unknown parameter values.

Specifying Workspaces, Service Account, and Pod Template

A Run object can specify workspaces, a service account name, or a pod template. These are intended to be used with custom tasks that create Pods or other resources that embed a Pod specification. The custom task can use these specifications to construct the Pod specification. Not all custom tasks will support these values. Consult the documentation of the custom task that you are using to determine whether these values apply.

Specifying workspaces

If the custom task supports it, you can provide Workspaces to share data with the custom task.

spec:
  workspaces:
    - name: my-workspace
      emptyDir: {}

Consult the documentation of the custom task that you are using to determine whether it supports workspaces and how to name them.

Specifying a ServiceAccount

If the custom task supports it, you can execute the Run with a specific set of credentials by specifying a ServiceAccount object name in the serviceAccountName field in your Run definition. If you do not explicitly specify this, the Run executes with the service account specified in the configmap-defaults ConfigMap. If this default is not specified, Runs will execute with the default service account set for the target namespace.

spec:
  serviceAccountName: my-account

Consult the documentation of the custom task that you are using to determine whether it supports a service account name.

Specifying a pod template

If the custom task supports it, you can specify a Pod template configuration that the custom task will use to configure Pods (or other resources that embed a Pod specification) that it creates.

spec:
  podTemplate:
    securityContext:
      runAsUser: 1001

Consult the documentation of the custom task that you are using to determine whether it supports a pod template.

Monitoring execution status

As your Run executes, its status field accumulates information on the execution of the Run. This information includes start and completion times, and any output results reported by the custom task controller.

The following example shows the status field of a Run that has executed successfully:

completionTime: "2019-08-12T18:22:57Z"
conditions:
  - lastTransitionTime: "2019-08-12T18:22:57Z"
    message: Execution was successful
    reason: Succeeded
    status: "True"
    type: Succeeded
startTime: "2019-08-12T18:22:51Z"

The following tables shows how to read the overall status of a Run:

status	Description
	The custom task controller has not taken any action on the Run.
Unknown	The custom task controller has started execution and the Run is ongoing.
True	The Run completed successfully.
False	The Run completed unsuccessfully.

In any case, the custom task controller should populate the reason and message fields to provide more information about the status of the execution.

Monitoring Results

After the Run completes, the custom task controller can report output values in the results field:

results:
- name: my-result
  value: chicken

Code examples

To better understand Runs, study the following code examples:

• Example Run with a referenced custom task
• Example Run with an unnamed custom task
• Example of specifying parameters

Example Run with a referenced custom task

In this example, a Run named my-example-run invokes a custom task of the v1alpha1 version of the Example kind in the example.dev API group, with the name my-example-task.

In this case the custom task controller is expected to look up the Example resource named my-example-task and to use that configuration to configure the execution of the Run.

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: my-example-run
spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example-task

Example Run with an unnamed custom task

In this example, a Run named my-example-run invokes a custom task of the v1alpha1 version of the Example kind in the example.dev API group, without a specified name.

In this case the custom task controller is expected to provide some default behavior when the referenced task is unnamed.

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: my-example-run
spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example

Example of specifying parameters

In this example, a Run named my-example-run invokes a custom task, and specifies some parameter values to further configure the execution's behavior.

In this case the custom task controller is expected to validate and interpret these parameter values and use them to configure the Run's execution.

apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: my-example-run
spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example-task
  params:
    - name: my-first-param
      value: i'm number one
    - name: my-second-param
      value: close second