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

@@ -4534,6 +4534,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
@@ -5052,7 +5064,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>
@@ -7329,7 +7341,7 @@ Refer Go&rsquo;s ParseDuration documentation for expected format: <a href="https
 (<em>Appears on:</em><a href="#tekton.dev/v1alpha1.StepActionSpec">StepActionSpec</a>)
 </p>
 <div>
-<p>StepActionResult used to describe the results of a task</p>
+<p>StepActionResult used to describe the results of a StepAction</p>
 </div>
 <table>
 <thead>
@@ -13426,6 +13438,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
@@ -14328,7 +14352,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)
 ```
 
+In the above example, it is possible that the same `StepAction` is used multiple times in the same `Task` or multiple `StepActions` in the same `Task` produce a result that has the same name, resolving the 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. 
+
+The above `StepAction` 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 `StepAciton` can be [fetched by the `Task`](#fetching-emitted-results-from-step-actions) using this `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 called "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`:

hack/ignored-openapi-violations.list

@@ -49,3 +49,4 @@ 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

pkg/apis/pipeline/v1/result_types.go

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

pkg/apis/pipeline/v1/swagger.json

@@ -1556,6 +1556,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               []StepResult `json:"results,omitempty"`
 }
 
 // SidecarState reports the results of running a sidecar in a Task.

pkg/apis/pipeline/v1alpha1/result_types.go

@@ -19,7 +19,7 @@ import (
 	v1 "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1"
 )
 
-// StepActionResult used to describe the results of a task
+// StepActionResult used to describe the results of a StepAction
 type StepActionResult struct {
 	// Name the given name
 	Name string `json:"name"`

pkg/apis/pipeline/v1alpha1/swagger.json

@@ -385,7 +385,7 @@
       }
     },
     "v1alpha1.StepActionResult": {
-      "description": "StepActionResult used to describe the results of a task",
+      "description": "StepActionResult used to describe the results of a StepAction",
       "type": "object",
       "required": [
         "name"

pkg/apis/pipeline/v1beta1/result_types.go

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

pkg/apis/pipeline/v1beta1/swagger.json

@@ -2211,6 +2211,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.StepResult{}
+		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 := StepResult{}
+		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_types.go

@@ -367,9 +367,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"`
-	ContainerName         string `json:"container,omitempty"`
-	ImageID               string `json:"imageID,omitempty"`
+	Name                  string       `json:"name,omitempty"`
+	ContainerName         string       `json:"container,omitempty"`
+	ImageID               string       `json:"imageID,omitempty"`
+	Results               []StepResult `json:"results,omitempty"`
 }
 
 // SidecarState reports the results of running a sidecar in a Task.