[TEP-0050] Add OnError field and documentation

In [TEP-0050][tep-0050], we proposed to add an `OnError` API field under `PipelineTask` to configure error handling strategy. This commits add the new `OnError` API field and the related documentations. The validation and business logic will be added in the follow-up PRs. Note: OnError is in preview mode and not yet supported. /kind feature [tep-0050]: https://github.com/tektoncd/community/blob/main/teps/0050-ignore-task-failures.md
tektoncd · Sep 28, 2023 · 9acd0bd · 9acd0bd
1 parent c2858d8
commit 9acd0bd
Show file tree

Hide file tree

Showing 8 changed files with 217 additions and 0 deletions.
diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -2851,6 +2851,23 @@ PipelineSpec
 Note: PipelineSpec is in preview mode and not yet supported</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>onError</code><br/>
+<em>
+<a href="#tekton.dev/v1.PipelineTaskOnErrorType">
+PipelineTaskOnErrorType
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>OnError defines the exiting behavior of a PipelineRun on error
+can be set to [ continue | stopAndFail ]
+Note: OnError is in preview mode and not yet supported
+TODO(@QuanZhang-William)</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.PipelineTaskMetadata">PipelineTaskMetadata
@@ -2893,6 +2910,29 @@ map[string]string
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1.PipelineTaskOnErrorType">PipelineTaskOnErrorType
+(<code>string</code> alias)</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
+</p>
+<div>
+<p>PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr><td><p>&#34;continue&#34;</p></td>
+<td><p>PipelineTaskContinue indicates to continue executing the rest of the DAG when the PipelineTask fails</p>
+</td>
+</tr><tr><td><p>&#34;stopAndFail&#34;</p></td>
+<td><p>PipelineTaskStopAndFail indicates to stop and fail the PipelineRun if the PipelineTask fails</p>
+</td>
+</tr></tbody>
+</table>
 <h3 id="tekton.dev/v1.PipelineTaskParam">PipelineTaskParam
 </h3>
 <div>
@@ -10900,6 +10940,23 @@ PipelineSpec
 Note: PipelineSpec is in preview mode and not yet supported</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>onError</code><br/>
+<em>
+<a href="#tekton.dev/v1beta1.PipelineTaskOnErrorType">
+PipelineTaskOnErrorType
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>OnError defines the exiting behavior of a PipelineRun on error
+can be set to [ continue | stopAndFail ]
+Note: OnError is in preview mode and not yet supported
+TODO(@QuanZhang-William)</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1beta1.PipelineTaskInputResource">PipelineTaskInputResource
@@ -10998,6 +11055,14 @@ map[string]string
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1beta1.PipelineTaskOnErrorType">PipelineTaskOnErrorType
+(<code>string</code> alias)</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
+</p>
+<div>
+<p>PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error</p>
+</div>
 <h3 id="tekton.dev/v1beta1.PipelineTaskOutputResource">PipelineTaskOutputResource
 </h3>
 <p>

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -21,6 +21,8 @@ weight: 203
     - [Tekton Bundles](#tekton-bundles)
     - [Using the `runAfter` field](#using-the-runafter-field)
     - [Using the `retries` field](#using-the-retries-field)
+    - [Using the `onError` field](#using-the-retries-field)
+    - [Produce results with `OnError`](#produce-results-with-onerror)
     - [Guard `Task` execution using `when` expressions](#guard-task-execution-using-when-expressions)
       - [Guarding a `Task` and its dependent `Tasks`](#guarding-a-task-and-its-dependent-tasks)
         - [Cascade `when` expressions to the specific dependent `Tasks`](#cascade-when-expressions-to-the-specific-dependent-tasks)
@@ -606,6 +608,106 @@ tasks:
       name: build-push
 ```
 
+### Using the `onError` field
+
+> :seedling: **Specifying `onError` in `PipelineTasks` is an [alpha](additional-configs.md#alpha-features) feature.** The `enable-api-fields` feature flag must be set to `"alpha"` to specify `onError`  in a `PipelineTask`.
+
+> :seedling: This feature is in **Preview Only** mode and not yet supported/implemented.
+
+When a `PipelineTask` fails, the rest of the `PipelineTasks` are skipped and the `PipelineRun` is declared a failure. If you would like to
+ignore such `PipelineTask` failure and continue executing the rest of the `PipelineTasks`, you can specify `onError` for such a `PipelineTask`.
+
+`OnError` can be set to `stopAndFail` (default) and `continue`. The failure of a `PipelineTask` with `stopAndFail` would stop and fail the whole `PipelineRun`.  A `PipelineTask` fails with `continue` does not fail the whole `PipelineRun`, and the rest of the `PipelineTask` will continue to execute.
+
+To ignore a `PipelineTask` failure, set `onError` to `continue`:
+
+``` yaml
+apiVersion: tekton.dev/v1
+kind: Pipeline
+metadata:
+  name: demo
+spec:
+  tasks:
+    - name: task1
+      onError: continue
+      taskSpec:
+        steps:
+          - name: step1
+            image: alpine
+            script: |
+              exit 1
+```
+
+At runtime, the failure is ignored to determine the `PipelineRun` status. The `PipelineRun` `message` contains the ignored failure info:
+
+``` yaml
+status:
+  conditions:
+  - lastTransitionTime: "2023-09-28T19:08:30Z"
+    message: 'Tasks Completed: 1 (Failed: 1 (Ignored: 1), Cancelled 0), Skipped: 0'
+    reason: Succeeded
+    status: "True"
+    type: Succeeded
+  ...
+```
+
+Note that the `TaskRun` status remains as it is irrelevant to `OnError`. Failed but ignored `TaskRuns` result in a `failed` status with reason
+`FailureIgnored`.
+
+For example, the `TaskRun` created by the above `PipelineRun` has the following status:
+
+``` bash
+$ kubectl get tr demo-run-task1
+NAME                                SUCCEEDED   REASON           STARTTIME   COMPLETIONTIME
+demo-run-task1                      False       FailureIgnored   12m         12m
+```
+
+To specify `onError` for a `step`, please see [specifying onError for a step](./tasks.md#specifying-onerror-for-a-step).
+
+**Note:** Setting [`Retry`](#specifying-retries) and `OnError:continue` at the same time is **NOT** allowed.
+
+### Produce results with `OnError`
+
+When a `PipelineTask` is set to ignore error and the `PipelineTask` is able to initialize a result before failing, the result is made available to the consumer `PipelineTasks`.
+
+``` yaml
+  tasks:
+    - name: task1
+      onError: continue
+      taskSpec:
+        results:
+          - name: result1
+        steps:
+          - name: step1
+            image: alpine
+            script: |
+              echo -n 123 | tee $(results.result1.path)
+              exit 1
+```
+
+The consumer `PipelineTasks` can access the result by referencing `$(tasks.task1.results.result1)`.
+
+If the result is **NOT** initialized before failing, and there is a `PipelineTask` consuming it:
+
+``` yaml
+  tasks:
+    - name: task1
+      onError: continue
+      taskSpec:
+        results:
+          - name: result1
+        steps:
+          - name: step1
+            image: alpine
+            script: |
+              exit 1
+              echo -n 123 | tee $(results.result1.path)
+```
+
+- If the consuming `PipelineTask` has `OnError:stopAndFail`, the `PipelineRun` will fail with `InvalidTaskResultReference`.
+- If the consuming `PipelineTask` has `OnError:continue`, the consuming `PipelineTask` will be skipped with reason `Results were missing`, 
+and the `PipelineRun` will continue to execute.
+
 ### Guard `Task` execution using `when` expressions
 
 To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using the `when` field. The `when` field allows you to list a series of references to `when` expressions.

diff --git a/pkg/apis/pipeline/v1/openapi_generated.go b/pkg/apis/pipeline/v1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1/pipeline_types.go b/pkg/apis/pipeline/v1/pipeline_types.go
@@ -27,13 +27,20 @@ import (
 	"knative.dev/pkg/kmeta"
 )
 
+// PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error
+type PipelineTaskOnErrorType string
+
 const (
 	// PipelineTasksAggregateStatus is a param representing aggregate status of all dag pipelineTasks
 	PipelineTasksAggregateStatus = "tasks.status"
 	// PipelineTasks is a value representing a task is a member of "tasks" section of the pipeline
 	PipelineTasks = "tasks"
 	// PipelineFinallyTasks is a value representing a task is a member of "finally" section of the pipeline
 	PipelineFinallyTasks = "finally"
+	// PipelineTaskStopAndFail indicates to stop and fail the PipelineRun if the PipelineTask fails
+	PipelineTaskStopAndFail PipelineTaskOnErrorType = "stopAndFail"
+	// PipelineTaskContinue indicates to continue executing the rest of the DAG when the PipelineTask fails
+	PipelineTaskContinue PipelineTaskOnErrorType = "continue"
 )
 
 // +genclient
@@ -238,6 +245,13 @@ type PipelineTask struct {
 	// Note: PipelineSpec is in preview mode and not yet supported
 	// +optional
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
+
+	// OnError defines the exiting behavior of a PipelineRun on error
+	// can be set to [ continue | stopAndFail ]
+	// Note: OnError is in preview mode and not yet supported
+	// TODO(@QuanZhang-William)
+	// +optional
+	OnError PipelineTaskOnErrorType `json:"onError,omitempty"`
 }
 
 // IsCustomTask checks whether an embedded TaskSpec is a Custom Task

diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -885,6 +885,10 @@
           "description": "Name is the name of this task within the context of a Pipeline. Name is used as a coordinate with the `from` and `runAfter` fields to establish the execution order of tasks relative to one another.",
           "type": "string"
         },
+        "onError": {
+          "description": "OnError defines the exiting behavior of a PipelineRun on error can be set to [ continue | stopAndFail ] Note: OnError is in preview mode and not yet supported",
+          "type": "string"
+        },
         "params": {
           "description": "Parameters declares parameters passed to this task.",
           "type": "array",

diff --git a/pkg/apis/pipeline/v1beta1/openapi_generated.go b/pkg/apis/pipeline/v1beta1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1beta1/pipeline_types.go b/pkg/apis/pipeline/v1beta1/pipeline_types.go
@@ -27,13 +27,20 @@ import (
 	"knative.dev/pkg/kmeta"
 )
 
+// PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error
+type PipelineTaskOnErrorType string
+
 const (
 	// PipelineTasksAggregateStatus is a param representing aggregate status of all dag pipelineTasks
 	PipelineTasksAggregateStatus = "tasks.status"
 	// PipelineTasks is a value representing a task is a member of "tasks" section of the pipeline
 	PipelineTasks = "tasks"
 	// PipelineFinallyTasks is a value representing a task is a member of "finally" section of the pipeline
 	PipelineFinallyTasks = "finally"
+	// PipelineTaskStopAndFail indicates to stop and fail the PipelineRun if the PipelineTask fails
+	PipelineTaskStopAndFail PipelineTaskOnErrorType = "stopAndFail"
+	// PipelineTaskContinue indicates to continue executing the rest of the DAG when the PipelineTask fails
+	PipelineTaskContinue PipelineTaskOnErrorType = "continue"
 )
 
 // +genclient
@@ -252,6 +259,13 @@ type PipelineTask struct {
 	// Note: PipelineSpec is in preview mode and not yet supported
 	// +optional
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
+
+	// OnError defines the exiting behavior of a PipelineRun on error
+	// can be set to [ continue | stopAndFail ]
+	// Note: OnError is in preview mode and not yet supported
+	// TODO(@QuanZhang-William)
+	// +optional
+	OnError PipelineTaskOnErrorType `json:"onError,omitempty"`
 }
 
 // IsCustomTask checks whether an embedded TaskSpec is a Custom Task

diff --git a/pkg/apis/pipeline/v1beta1/swagger.json b/pkg/apis/pipeline/v1beta1/swagger.json
@@ -1278,6 +1278,10 @@
           "description": "Name is the name of this task within the context of a Pipeline. Name is used as a coordinate with the `from` and `runAfter` fields to establish the execution order of tasks relative to one another.",
           "type": "string"
         },
+        "onError": {
+          "description": "OnError defines the exiting behavior of a PipelineRun on error can be set to [ continue | stopAndFail ] Note: OnError is in preview mode and not yet supported",
+          "type": "string"
+        },
         "params": {
           "description": "Parameters declares parameters passed to this task.",
           "type": "array",