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>

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

pkg/entrypoint/entrypointer.go

@@ -96,6 +96,8 @@ type Entrypointer struct {
 	// PostWriter encapsulates writing files when complete.
 	PostWriter PostWriter
 
+	// StepResults is the set of files that might contain step results
+	StepResults []string
 	// Results is the set of files that might contain task results
 	Results []string
 	// Timeout is an optional user-specified duration within which the Step must complete
@@ -147,6 +149,9 @@ func (e Entrypointer) Go() error {
 		_ = logger.Sync()
 	}()
 
+	if err := os.MkdirAll(filepath.Join(e.StepMetadataDir, "results"), os.ModePerm); err != nil {
+		return err
+	}
 	for _, f := range e.WaitFiles {
 		if err := e.Waiter.Wait(context.Background(), f, e.WaitFileContent, e.BreakpointOnFailure); err != nil {
 			// An error happened while waiting, so we bail
@@ -237,17 +242,30 @@ func (e Entrypointer) Go() error {
 		if e.ResultsDirectory != "" {
 			resultPath = e.ResultsDirectory
 		}
-		if err := e.readResultsFromDisk(ctx, resultPath); err != nil {
+		if err := e.readResultsFromDisk(ctx, resultPath, result.TaskRunResultType); err != nil {
 			logger.Fatalf("Error while handling results: %s", err)
 		}
 	}
+	if len(e.StepResults) >= 1 && e.StepResults[0] != "" {
+		stepResultPath := filepath.Join(e.StepMetadataDir, "results")
+		if e.ResultsDirectory != "" {
+			stepResultPath = e.ResultsDirectory
+		}
+		if err := e.readResultsFromDisk(ctx, stepResultPath, result.StepResultType); err != nil {
+			logger.Fatalf("Error while handling step results: %s", err)
+		}
+	}
 
 	return err
 }
 
-func (e Entrypointer) readResultsFromDisk(ctx context.Context, resultDir string) error {
+func (e Entrypointer) readResultsFromDisk(ctx context.Context, resultDir string, resultType result.ResultType) error {
 	output := []result.RunResult{}
-	for _, resultFile := range e.Results {
+	results := e.Results
+	if resultType == result.StepResultType {
+		results = e.StepResults
+	}
+	for _, resultFile := range results {
 		if resultFile == "" {
 			continue
 		}
@@ -261,9 +279,10 @@ func (e Entrypointer) readResultsFromDisk(ctx context.Context, resultDir string)
 		output = append(output, result.RunResult{
 			Key:        resultFile,
 			Value:      string(fileContents),
-			ResultType: result.TaskRunResultType,
+			ResultType: resultType,
 		})
 	}
+
 	if e.SpireWorkloadAPI != nil {
 		signed, err := e.SpireWorkloadAPI.Sign(ctx, output)
 		if err != nil {

pkg/entrypoint/entrypointer_test.go

@@ -262,31 +262,62 @@ func TestReadResultsFromDisk(t *testing.T) {
 		desc          string
 		results       []string
 		resultContent []v1beta1.ResultValue
+		resultType    result.ResultType
 		want          []result.RunResult
 	}{{
 		desc:          "read string result file",
 		results:       []string{"results"},
 		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello world")},
+		resultType:    result.TaskRunResultType,
 		want: []result.RunResult{
 			{Value: `"hello world"`,
 				ResultType: 1}},
 	}, {
 		desc:          "read array result file",
 		results:       []string{"results"},
 		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello", "world")},
+		resultType:    result.TaskRunResultType,
 		want: []result.RunResult{
 			{Value: `["hello","world"]`,
 				ResultType: 1}},
 	}, {
 		desc:          "read string and array result files",
 		results:       []string{"resultsArray", "resultsString"},
 		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello", "world"), *v1beta1.NewStructuredValues("hello world")},
+		resultType:    result.TaskRunResultType,
 		want: []result.RunResult{
 			{Value: `["hello","world"]`,
 				ResultType: 1},
 			{Value: `"hello world"`,
 				ResultType: 1},
 		},
+	}, {
+		desc:          "read string step result file",
+		results:       []string{"results"},
+		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello world")},
+		resultType:    result.StepResultType,
+		want: []result.RunResult{
+			{Value: `"hello world"`,
+				ResultType: 4}},
+	}, {
+		desc:          "read array step result file",
+		results:       []string{"results"},
+		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello", "world")},
+		resultType:    result.StepResultType,
+		want: []result.RunResult{
+			{Value: `["hello","world"]`,
+				ResultType: 4}},
+	}, {
+		desc:          "read string and array step result files",
+		results:       []string{"resultsArray", "resultsString"},
+		resultContent: []v1beta1.ResultValue{*v1beta1.NewStructuredValues("hello", "world"), *v1beta1.NewStructuredValues("hello world")},
+		resultType:    result.StepResultType,
+		want: []result.RunResult{
+			{Value: `["hello","world"]`,
+				ResultType: 4},
+			{Value: `"hello world"`,
+				ResultType: 4},
+		},
 	},
 	} {
 		t.Run(c.desc, func(t *testing.T) {
@@ -319,10 +350,11 @@ func TestReadResultsFromDisk(t *testing.T) {
 
 			e := Entrypointer{
 				Results:                resultsFilePath,
+				StepResults:            resultsFilePath,
 				TerminationPath:        terminationPath,
 				ResultExtractionMethod: config.ResultExtractionMethodTerminationMessage,
 			}
-			if err := e.readResultsFromDisk(ctx, ""); err != nil {
+			if err := e.readResultsFromDisk(ctx, "", c.resultType); err != nil {
 				t.Fatal(err)
 			}
 			msg, err := os.ReadFile(terminationPath)
@@ -462,6 +494,12 @@ func TestEntrypointerResults(t *testing.T) {
 		resultsToWrite: map[string]string{
 			"foo": "abc",
 		},
+	}, {
+		desc:       "write single step result",
+		entrypoint: "echo",
+		resultsToWrite: map[string]string{
+			"foo": "abc",
+		},
 	}, {
 		desc:       "write multiple result",
 		entrypoint: "echo",
@@ -555,6 +593,7 @@ func TestEntrypointerResults(t *testing.T) {
 				Runner:                 fr,
 				PostWriter:             fpw,
 				Results:                results,
+				StepResults:            results,
 				ResultsDirectory:       resultsDir,
 				ResultExtractionMethod: config.ResultExtractionMethodTerminationMessage,
 				TerminationPath:        terminationPath,