tep to ignore step errors

Proposing a tep to ignore step errors and provide an option to
continue after capturing the non zero exit code. Also document the
container termination state to access it after the pipeline exectution finishes.

teps/0040-ignore-step-errors.md

@@ -0,0 +1,157 @@
+---
+status: proposed
+title: 'Ignore Step Errors'
+creation-date: '2021-01-06'
+last-updated: '2021-02-03'
+authors:
+- '@pritidesai'
+- '@afrittoli'
+- '@skaegi'
+---
+
+# TEP-0040: Ignore Step Errors
+
+<!-- toc -->
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Requirements](#requirements)
+  - [Use Cases](#use-cases)
+- [References](#references)
+<!-- /toc -->
+
+## Summary
+
+Tekton tasks are defined as a collection of steps in which each step can specify a container image to run.
+Steps are executed in order in which they are specified. One single step failure results in a task failure
+i.e. once a step results in a failure, rest of the steps are not executed. When a container exits with
+non-zero exit code, the step results in error:
+
+```yaml
+$ kubectl get tr failing-taskrun-hw5xj -o json | jq .status.steps
+[
+  {
+    "container": "step-failing-step",
+    "imageID": "...",
+    "name": "failing-step",
+    "terminated": {
+      "containerID": "...",
+      "exitCode": 244,
+      "finishedAt": "2021-02-02T18:27:46Z",
+      "reason": "Error",
+      "startedAt": "2021-02-02T18:27:46Z"
+    }
+  }
+]
+```
+
+`TaskRun` with such step error, stops executing subsequent steps and results in a failure:
+
+```yaml
+$ kubectl get tr failing-taskrun-hw5xj -o json | jq .status.conditions
+[
+  {
+    "lastTransitionTime": "2021-02-02T18:27:47Z",
+    "message": "\"step-failing-step\" exited with code 244 (image: \"..."); for logs run: kubectl -n default logs failing-taskrun-hw5xj-pod-wj6vn -c step-failing-step\n",
+    "reason": "Failed",
+    "status": "False",
+    "type": "Succeeded"
+  }
+]
+```
+
+If such a task with a failing step is part of a pipeline, the `pipelineRun` stops executing and subsequent steps in that
+task (similar to `taskRun`) stop executing any other task in the pipeline which results in a pipeline failure.
+
+```yaml
+$ kubectl get pr pipelinerun-with-failing-step-csmjr -o json | jq .status.conditions
+[
+  {
+    "lastTransitionTime": "2021-02-02T18:51:15Z",
+    "message": "Tasks Completed: 1 (Failed: 1, Cancelled 0), Skipped: 3",
+    "reason": "Failed",
+    "status": "False",
+    "type": "Succeeded"
+  }
+]
+```
+
+Many common tasks have the requirement where a step failure must not stop executing the rest of the steps.
+In order to continue executing subsequent steps, task authors have the flexibility of wrapping an image and
+exiting that step with success. This changes the failing step into a success and does not block further
+execution. But, this is a workaround and only works with images that can be wrapped:
+
+```shell
+    steps:
+    - image: docker.io/library/golang:latest
+      name: ignore-unit-test-failure
+      script: |
+        go test .
+        TEST_EXIT_CODE=$?
+        if [ $TEST_EXIT_CODE != 0 ]; then
+          exit 0
+        fi
+```
+
+This workaround does not apply to off-the-shelf container images.
+
+As a pipeline execution engine, we want to support off-the-shelf container images as a step, and provide
+the option to ignore such step errors. The task author can choose to continue execution, capture the original non-zero
+exit code, and make it available for the rest of the steps in that task.
+
+Issue: [tektoncd/pipeline#2800](https://github.com/tektoncd/pipeline/issues/2800)
+
+
+## Motivation
+
+It should be possible to easily use off-the-shelf (OTS) images as steps in Tekton tasks. A task author has no
+control over the image but may desire to ignore an error and continue executing the rest of the steps.
+
+
+### Goals
+
+Design a step failure strategy so that the task author can control the behaviour of the underlying step and decide
+whether to continue executing the rest of the steps in the event of failure.
+
+Store the step container's termination state and make it accessible to the rest of the steps in a task.
+
+Be applicable to any container image including custom or off-the-shelf images.
+
+### Non-Goals
+
+This proposal is limited to a step within a task and does not address `pipelineTask` level failure case.
+
+## Requirements
+
+* Users should be able to use prebuilt images as-is without having to understand if a shell or similar capability exists
+  in an image and then altering the entrypoint to allow capturing errors.
+
+* It should be possible to know that a step failed and subsequent steps allowed to continue by observing the status of
+  the `TaskRun`.
+
+* When a step is allowed to fail, the exit code of the process that failed should not be lost and should at a minimum be
+  available in the status of the `TaskRun`.
+
+
+### Use Cases
+
+* As a task author, I would like to design a task where one or more steps running unit tests might fail,
+  but want the task to succeed, so that a later task can analyze and report results.
+
+* As a new Tekton user, I want to migrate existing scripts and automations from other CI/CD systems that allowed a
+  similar step unit of failure.
+
+* A [platform team](https://github.com/tektoncd/community/blob/master/user-profiles.md#1-pipeline-and-task-authors)
+  wants to share a `Task` with their team which runs the following steps in a sequence:
+  * Run unit tests (which may fail)
+  * Apply a transformation to the test results (e.g. converts them to a certain format such as junit)
+  * Upload the results to a central location used by all the teams
+
+
+## References
+
+* [Capture Exit Code, tektoncd/pipeline#2800](https://github.com/tektoncd/pipeline/issues/2800)
+* [Add a field to Step that allows it to ignore failed prior Steps *within the same Task, tektoncd/pipeline#1559](https://github.com/tektoncd/pipeline/issues/1559)
+* [Scott's Changes to allow steps to run regardless of previous step errors](https://github.com/tektoncd/pipeline/pull/1573)
+* [Christie's Notes](https://docs.google.com/document/d/11wygsRe2d4G-wTJMddIdBgSOB5TpsWCqGGACSXusy_U/edit?resourcekey=0-skOAYQiz0xIktxYxCm-SFg) - Thank You, Christie!

teps/README.md

@@ -149,4 +149,5 @@ This is the complete list of Tekton teps:
 |[TEP-0036](0036-start-measuring-tekton-pipelines-performance.md) | Start Measuring Tekton Pipelines Performance | proposed | 2020-11-20 |
 |[TEP-0037](0037-remove-gcs-fetcher.md) | Remove `gcs-fetcher` image | implementing | 2021-01-27 |
 |[TEP-0039](0039-add-variable-retries-and-retrycount.md) | Add Variable `retries` and `retry-count` | proposed | 2021-01-31 |
+|[TEP-0040](0040-ignore-step-errors.md) | Ignore Step Errors | proposed | 2021-02-04 |
 |[TEP-0045](0045-whenexpressions-in-finally-tasks.md) | WhenExpressions in Finally Tasks | implementable | 2021-01-28 |