TEP-0142: Surface step results via termination message

This PR surfaces step results (i.e results written to $(step.results.<resultName>.path)) via termination messages.  A followup PR will handle surfacing the results via sidecar logs.

cmd/entrypoint/main.go

@@ -49,6 +49,7 @@ var (
 	postFile            = flag.String("post_file", "", "If specified, file to write upon completion")
 	terminationPath     = flag.String("termination_path", "/tekton/termination", "If specified, file to write upon termination")
 	results             = flag.String("results", "", "If specified, list of file names that might contain task results")
+	stepResults         = flag.String("step_results", "", "step results if specified")
 	timeout             = flag.Duration("timeout", time.Duration(0), "If specified, sets timeout for step")
 	stdoutPath          = flag.String("stdout_path", "", "If specified, file to copy stdout to")
 	stderrPath          = flag.String("stderr_path", "", "If specified, file to copy stderr to")
@@ -159,6 +160,7 @@ func main() {
 		},
 		PostWriter:             &realPostWriter{},
 		Results:                strings.Split(*results, ","),
+		StepResults:            strings.Split(*stepResults, ","),
 		Timeout:                timeout,
 		BreakpointOnFailure:    *breakpointOnFailure,
 		OnError:                *onError,

docs/pipeline-api.md

@@ -4622,6 +4622,18 @@ string
 <td>
 </td>
 </tr>
+<tr>
+<td>
+<code>results</code><br/>
+<em>
+<a href="#tekton.dev/v1.TaskRunResult">
+[]TaskRunResult
+</a>
+</em>
+</td>
+<td>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.StepTemplate">StepTemplate
@@ -5140,7 +5152,7 @@ reasons that emerge from underlying resources are not included here</p>
 <h3 id="tekton.dev/v1.TaskRunResult">TaskRunResult
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.TaskRunStatusFields">TaskRunStatusFields</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.StepState">StepState</a>, <a href="#tekton.dev/v1.TaskRunStatusFields">TaskRunStatusFields</a>)
 </p>
 <div>
 <p>TaskRunResult used to describe the results of a task</p>
@@ -13462,6 +13474,18 @@ string
 <td>
 </td>
 </tr>
+<tr>
+<td>
+<code>results</code><br/>
+<em>
+<a href="#tekton.dev/v1beta1.TaskRunResult">
+[]TaskRunResult
+</a>
+</em>
+</td>
+<td>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1beta1.StepTemplate">StepTemplate
@@ -14364,7 +14388,7 @@ reasons that emerge from underlying resources are not included here</p>
 <h3 id="tekton.dev/v1beta1.TaskRunResult">TaskRunResult
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1beta1.TaskRunStatusFields">TaskRunStatusFields</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.StepState">StepState</a>, <a href="#tekton.dev/v1beta1.TaskRunStatusFields">TaskRunStatusFields</a>)
 </p>
 <div>
 <p>TaskRunResult used to describe the results of a task</p>

docs/stepactions.md

@@ -39,7 +39,7 @@ A `StepAction` definition supports the following fields:
     - cannot be used at the same time as using `command`.
   - `env`
   - [`params`](#declaring-params)
-  - [`results`](#declaring-results)
+  - [`results`](#emitting-results)
   - [`securityContext`](#declaring-securitycontext)
   - [`volumeMounts`](#declaring-volumemounts)
 
@@ -93,7 +93,7 @@ spec:
   ]
 ```
 
-### Declaring Results
+### Emitting Results
 
 A `StepAction` also declares the results that it will emit.
 
@@ -115,6 +115,85 @@ spec:
     date | tee $(results.current-date-human-readable.path)
 ```
 
+It is possible that a `StepAction` with `Results` is used multiple times in the same `Task` or multiple `StepActions` in the same `Task` produce `Results` with the same name. Resolving the `Result` names becomes critical otherwise there could be unexpected outcomes. The `Task` needs to be able to resolve these `Result` names clashes by mapping it to a different `Result` name. For this reason, we introduce the capability to store results on a `Step` level. 
+
+`StepActions` can also emit `Results` to `$(step.results.<resultName>.path)`.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: stepaction-declaring-results
+spec:
+  results:
+    - name: current-date-unix-timestamp
+      description: The current date in unix timestamp format
+    - name: current-date-human-readable
+      description: The current date in human readable format
+  image: bash:latest
+  script: |
+    #!/usr/bin/env bash
+    date +%s | tee $(step.results.current-date-unix-timestamp.path)
+    date | tee $(step.results.current-date-human-readable.path)
+```
+
+`Results` from the above `StepAction` can be [fetched by the `Task`](#fetching-emitted-results-from-step-actions) in another `StepAction` via `$(steps.<stepName>.results.<resultName>)`.
+
+#### Fetching Emitted Results from StepActions
+
+A `Task` can fetch `Results` produced by the `StepActions` (i.e. only `Results` emitted to `$(step.results.<resultName>.path)`, `NOT` $(results.<resultName>.path)) using variable replacement syntax. We introduce a field to [`Task Results`](./tasks.md#emitting-results) called `Value` whose value can be set to the variable `$(steps.<stepName>.results.<resultName>)`.
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: task-fetching-results
+spec:
+  results:
+    - name: git-url
+      description: "url of git repo"
+      value: $(steps.git-clone.results.url)
+    - name: registry-url
+      description: "url of docker registry"
+      value: $(steps.kaniko.results.url)
+  steps:
+    - name: git-clone
+      ref:
+        name: clone-step-action
+    - name: kaniko
+      ref:
+        name: kaniko-step-action
+```
+
+`Results` emitted to `$(step.results.<resultName>.path)` are not automatically available as `TaskRun Results`. The `Task` must explicitly fetch it from the underlying `Step` referencing `StepActions`.
+
+For example, lets assume that in the previous example, the "kaniko" `StepAction` also produced a `Result` named "digest". In that case, the `Task` should also fetch the "digest" from "kaniko" `Step`.
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: task-fetching-results
+spec:
+  results:
+    - name: git-url
+      description: "url of git repo"
+      value: $(steps.git-clone.results.url)
+    - name: registry-url
+      description: "url of docker registry"
+      value: $(steps.kaniko.results.url)
+    - name: digest
+      description: "digest of the image"
+      value: $(steps.kaniko.results.digest)
+  steps:
+    - name: git-clone
+      ref:
+        name: clone-step-action
+    - name: kaniko
+      ref:
+        name: kaniko-step-action
+```
+
 ### Declaring SecurityContext
 
 You can declare `securityContext` in a `StepAction`:

examples/v1/taskruns/no-ci/stepaction-results.yaml

@@ -0,0 +1,24 @@
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: step-action
+spec:
+  image: alpine
+  results:
+    - name: result1
+  script: |
+    echo "I am a Step Action!!!" >> $(step.results.result1.path)
+---
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    results:
+      - name: step-result
+        value: $(steps.action-runner.results.result1)
+    steps:
+      - name: action-runner
+        ref:
+          name: step-action

hack/ignored-openapi-violations.list

@@ -49,3 +49,5 @@ API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipe
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Resources
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamSpec,Enum
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamSpec,Enum
+API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,StepState,Results
+API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepState,Results

pkg/apis/pipeline/v1/result_types.go

@@ -72,6 +72,9 @@ type TaskRunResult struct {
 	Value ResultValue `json:"value"`
 }
 
+// StepRunResult is a type alias of TaskRunResult
+type StepRunResult = TaskRunResult
+
 // ResultValue is a type alias of ParamValue
 type ResultValue = ParamValue
 

pkg/apis/pipeline/v1/swagger.json

@@ -1595,6 +1595,13 @@
         "name": {
           "type": "string"
         },
+        "results": {
+          "type": "array",
+          "items": {
+            "default": {},
+            "$ref": "#/definitions/v1.TaskRunResult"
+          }
+        },
         "running": {
           "description": "Details about a running container",
           "$ref": "#/definitions/v1.ContainerStateRunning"

pkg/apis/pipeline/v1/taskrun_types.go

@@ -338,9 +338,10 @@ func (trs *TaskRunStatus) SetCondition(newCond *apis.Condition) {
 // StepState reports the results of running a step in a Task.
 type StepState struct {
 	corev1.ContainerState `json:",inline"`
-	Name                  string `json:"name,omitempty"`
-	Container             string `json:"container,omitempty"`
-	ImageID               string `json:"imageID,omitempty"`
+	Name                  string          `json:"name,omitempty"`
+	Container             string          `json:"container,omitempty"`
+	ImageID               string          `json:"imageID,omitempty"`
+	Results               []StepRunResult `json:"results,omitempty"`
 }
 
 // SidecarState reports the results of running a sidecar in a Task.

pkg/apis/pipeline/v1beta1/result_types.go

@@ -52,6 +52,9 @@ type TaskRunResult struct {
 	Value ResultValue `json:"value"`
 }
 
+// StepRunResult is a type alias of TaskRunResult
+type StepRunResult = TaskRunResult
+
 // ResultValue is a type alias of ParamValue
 type ResultValue = ParamValue
 

pkg/apis/pipeline/v1beta1/swagger.json

@@ -2220,6 +2220,13 @@
         "name": {
           "type": "string"
         },
+        "results": {
+          "type": "array",
+          "items": {
+            "default": {},
+            "$ref": "#/definitions/v1beta1.TaskRunResult"
+          }
+        },
         "running": {
           "description": "Details about a running container",
           "$ref": "#/definitions/v1.ContainerStateRunning"

pkg/apis/pipeline/v1beta1/taskrun_conversion.go

@@ -330,13 +330,25 @@ func (ss StepState) convertTo(ctx context.Context, sink *v1.StepState) {
 	sink.Name = ss.Name
 	sink.Container = ss.ContainerName
 	sink.ImageID = ss.ImageID
+	sink.Results = nil
+	for _, r := range ss.Results {
+		new := v1.StepRunResult{}
+		r.convertTo(ctx, &new)
+		sink.Results = append(sink.Results, new)
+	}
 }
 
 func (ss *StepState) convertFrom(ctx context.Context, source v1.StepState) {
 	ss.ContainerState = source.ContainerState
 	ss.Name = source.Name
 	ss.ContainerName = source.Container
 	ss.ImageID = source.ImageID
+	ss.Results = nil
+	for _, r := range source.Results {
+		new := StepRunResult{}
+		new.convertFrom(ctx, r)
+		ss.Results = append(ss.Results, new)
+	}
 }
 
 func (trr TaskRunResult) convertTo(ctx context.Context, sink *v1.TaskRunResult) {

pkg/apis/pipeline/v1beta1/taskrun_conversion_test.go

@@ -102,6 +102,29 @@ func TestTaskRunConversion(t *testing.T) {
 				},
 			},
 		},
+	}, {
+		name: "taskrun with step Results in step state",
+		in: &v1beta1.TaskRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "foo",
+				Namespace: "bar",
+			},
+			Spec: v1beta1.TaskRunSpec{},
+			Status: v1beta1.TaskRunStatus{
+				TaskRunStatusFields: v1beta1.TaskRunStatusFields{
+					Steps: []v1beta1.StepState{{
+						Results: []v1beta1.StepRunResult{{
+							Name: "foo",
+							Type: v1beta1.ResultsTypeString,
+							Value: v1beta1.ResultValue{
+								Type:      v1beta1.ParamTypeString,
+								StringVal: "bar",
+							},
+						}},
+					}},
+				},
+			},
+		},
 	}, {
 		name: "taskrun conversion all non deprecated fields",
 		in: &v1beta1.TaskRun{