onErrorOnError 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)
+string alias)+(Appears on:PipelineTask) +
+PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error
+| Value | +Description | +
|---|---|
"continue" |
+PipelineTaskContinue indicates to continue executing the rest of the DAG when the PipelineTask fails + |
+
"stopAndFail" |
+PipelineTaskStopAndFail indicates to stop and fail the PipelineRun if the PipelineTask fails + |
+
onErrorOnError 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)
+string alias)+(Appears on:PipelineTask) +
+PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error
+diff --git a/docs/pipelines.md b/docs/pipelines.md index 13fc80d461f..189edc8ad5d 100644 --- 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 index c3011075abc..c766a3f1df9 100644 --- a/pkg/apis/pipeline/v1/openapi_generated.go +++ b/pkg/apis/pipeline/v1/openapi_generated.go @@ -1891,6 +1891,13 @@ func schema_pkg_apis_pipeline_v1_PipelineTask(ref common.ReferenceCallback) comm Ref: ref("github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PipelineSpec"), }, }, + "onError": { + SchemaProps: spec.SchemaProps{ + 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{"string"}, + Format: "", + }, + }, }, }, }, diff --git a/pkg/apis/pipeline/v1/pipeline_types.go b/pkg/apis/pipeline/v1/pipeline_types.go index 25613f1a41a..05f339290a5 100644 --- a/pkg/apis/pipeline/v1/pipeline_types.go +++ b/pkg/apis/pipeline/v1/pipeline_types.go @@ -27,6 +27,9 @@ 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" @@ -34,6 +37,10 @@ const ( 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 index e2f82a64734..5ffcdf4385b 100644 --- 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 index 71844dd01d9..7d2ad4cfaa8 100644 --- a/pkg/apis/pipeline/v1beta1/openapi_generated.go +++ b/pkg/apis/pipeline/v1beta1/openapi_generated.go @@ -2648,6 +2648,13 @@ func schema_pkg_apis_pipeline_v1beta1_PipelineTask(ref common.ReferenceCallback) Ref: ref("github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.PipelineSpec"), }, }, + "onError": { + SchemaProps: spec.SchemaProps{ + 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{"string"}, + Format: "", + }, + }, }, }, }, diff --git a/pkg/apis/pipeline/v1beta1/pipeline_types.go b/pkg/apis/pipeline/v1beta1/pipeline_types.go index bbe837a94e5..d44234c7486 100644 --- a/pkg/apis/pipeline/v1beta1/pipeline_types.go +++ b/pkg/apis/pipeline/v1beta1/pipeline_types.go @@ -27,6 +27,9 @@ 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" @@ -34,6 +37,10 @@ const ( 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 index 47aafa9a098..321fe0ef463 100644 --- 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",