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,8 @@ 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")
+	stepName            = flag.String("step_name", "", "Name of the step")
 	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,11 +161,13 @@ func main() {
 		},
 		PostWriter:             &realPostWriter{},
 		Results:                strings.Split(*results, ","),
+		StepResults:            strings.Split(*stepResults, ","),
 		Timeout:                timeout,
 		BreakpointOnFailure:    *breakpointOnFailure,
 		OnError:                *onError,
 		StepMetadataDir:        *stepMetadataDir,
 		SpireWorkloadAPI:       spireWorkloadAPI,
+		StepName:               *stepName,
 		ResultExtractionMethod: *resultExtractionMethod,
 	}
 

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 when the same `StepAction` is used multiple times in the same `Task` or if 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 differen 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)
+    - nane: 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/alpha/stepaction-results.yaml

@@ -0,0 +1,56 @@
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: step-action-uri
+spec:
+  results:
+    - name: uri
+  params:
+    - name: uri
+  image: alpine
+  script: |
+    echo $(params.uri) > $(step.results.uri.path)
+---
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: step-action-uri-digest
+spec:
+  results:
+    - name: digest
+    - name: uri
+  params:
+    - name: uri
+    - name: digest
+  image: alpine
+  script: |
+    echo $(params.digest) > $(step.results.digest.path)
+    echo $(params.uri) > $(step.results.uri.path)
+---
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    results:
+      - name: step-1-uri
+        value: $(steps.step1.results.uri)
+      - name: step-2-uri
+        value: $(steps.step2.results.uri)
+      - name: digest
+    steps:
+      - name: step1
+        ref:
+          name: step-action-uri
+        params:
+          - name: uri
+            value: "https://github.com/tektoncd/pipeline"
+      - name: step2
+        ref:
+          name: step-action-uri-digest
+        params:
+          - name: uri
+            value: "https://github.com/tektoncd/other"
+          - name: digest
+            value: "c8381846241cac4c93c30b6a5ac04cac51fa0a6e"

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
@@ -110,6 +112,8 @@ type Entrypointer struct {
 	StepMetadataDir string
 	// SpireWorkloadAPI connects to spire and does obtains SVID based on taskrun
 	SpireWorkloadAPI spire.EntrypointerAPIClient
+	// StepName is the name of the step
+	StepName string
 	// ResultsDirectory is the directory to find results, defaults to pipeline.DefaultResultPath
 	ResultsDirectory string
 	// ResultExtractionMethod is the method using which the controller extracts the results from the task pod.
@@ -136,6 +140,7 @@ type PostWriter interface {
 // Go optionally waits for a file, runs the command, and writes a
 // post file.
 func (e Entrypointer) Go() error {
+	var err error
 	prod, _ := zap.NewProduction()
 	logger := prod.Sugar()
 
@@ -147,6 +152,11 @@ func (e Entrypointer) Go() error {
 		_ = logger.Sync()
 	}()
 
+	if e.StepName != "" && e.StepResults != nil {
+		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
@@ -170,7 +180,6 @@ func (e Entrypointer) Go() error {
 		ResultType: result.InternalTektonResultType,
 	})
 
-	var err error
 	if e.Timeout != nil && *e.Timeout < time.Duration(0) {
 		err = fmt.Errorf("negative timeout specified")
 	}
@@ -232,7 +241,7 @@ func (e Entrypointer) Go() error {
 
 	// strings.Split(..) with an empty string returns an array that contains one element, an empty string.
 	// This creates an error when trying to open the result folder as a file.
-	if len(e.Results) >= 1 && e.Results[0] != "" {
+	if (len(e.Results) >= 1 && e.Results[0] != "") || (len(e.StepResults) >= 1 && e.StepResults[0] != "") {
 		resultPath := pipeline.DefaultResultPath
 		if e.ResultsDirectory != "" {
 			resultPath = e.ResultsDirectory
@@ -264,6 +273,22 @@ func (e Entrypointer) readResultsFromDisk(ctx context.Context, resultDir string)
 			ResultType: result.TaskRunResultType,
 		})
 	}
+	for _, resultFile := range e.StepResults {
+		if resultFile == "" {
+			continue
+		}
+		fileContents, err := os.ReadFile(filepath.Join(pipeline.StepsDir, fmt.Sprintf("%s%s", pod.StepPrefix, e.StepName), "results", resultFile))
+		if os.IsNotExist(err) {
+			continue
+		} else if err != nil {
+			return err
+		}
+		output = append(output, result.RunResult{
+			Key:        fmt.Sprintf("%s.%s", e.StepName, resultFile),
+			Value:      string(fileContents),
+			ResultType: result.StepResultType,
+		})
+	}
 	if e.SpireWorkloadAPI != nil {
 		signed, err := e.SpireWorkloadAPI.Sign(ctx, output)
 		if err != nil {

pkg/pod/entrypoint.go

@@ -57,7 +57,8 @@ const (
 	readyAnnotation        = "tekton.dev/ready"
 	readyAnnotationValue   = "READY"
 
-	stepPrefix    = "step-"
+	// StepPrefix is the prefix applied to the container name of a step container.
+	StepPrefix    = "step-"
 	sidecarPrefix = "sidecar-"
 
 	downwardMountCancelFile = "cancel"
@@ -124,7 +125,7 @@ var (
 // command, we must have fetched the image's ENTRYPOINT before calling this
 // method, using entrypoint_lookup.go.
 // Additionally, Step timeouts are added as entrypoint flag.
-func orderContainers(commonExtraEntrypointArgs []string, steps []corev1.Container, taskSpec *v1.TaskSpec, breakpointConfig *v1.TaskRunDebug, waitForReadyAnnotation, enableKeepPodOnCancel bool) ([]corev1.Container, error) {
+func orderContainers(ctx context.Context, commonExtraEntrypointArgs []string, steps []corev1.Container, taskSpec *v1.TaskSpec, breakpointConfig *v1.TaskRunDebug, waitForReadyAnnotation, enableKeepPodOnCancel bool) ([]corev1.Container, error) {
 	if len(steps) == 0 {
 		return nil, errors.New("No steps specified")
 	}
@@ -149,6 +150,14 @@ func orderContainers(commonExtraEntrypointArgs []string, steps []corev1.Containe
 			"-termination_path", terminationPath,
 			"-step_metadata_dir", filepath.Join(RunDir, idx, "status"),
 		)
+		if config.FromContextOrDefaults(ctx).FeatureFlags.EnableStepActions {
+			stepName := s.Name
+			if s.Name == "" {
+				stepName = fmt.Sprintf("unnamed-%d", i)
+			}
+			argsForEntrypoint = append(argsForEntrypoint, "-step_name", stepName)
+		}
+
 		argsForEntrypoint = append(argsForEntrypoint, commonExtraEntrypointArgs...)
 		if taskSpec != nil {
 			if taskSpec.Steps != nil && len(taskSpec.Steps) >= i+1 {
@@ -170,6 +179,13 @@ func orderContainers(commonExtraEntrypointArgs []string, steps []corev1.Containe
 				}
 			}
 			argsForEntrypoint = append(argsForEntrypoint, resultArgument(steps, taskSpec.Results)...)
+			if config.FromContextOrDefaults(ctx).FeatureFlags.EnableStepActions {
+				stepResultArgs, err := stepResultArgument(taskSpec.Results, s.Name)
+				if err != nil {
+					return nil, err
+				}
+				argsForEntrypoint = append(argsForEntrypoint, stepResultArgs...)
+			}
 		}
 
 		if breakpointConfig != nil && breakpointConfig.NeedsDebugOnFailure() {
@@ -199,6 +215,34 @@ func orderContainers(commonExtraEntrypointArgs []string, steps []corev1.Containe
 	return steps, nil
 }
 
+func stepResultArgument(results []v1.TaskResult, stepName string) ([]string, error) {
+	if len(results) == 0 {
+		return nil, nil
+	}
+	if stepName == "" {
+		return nil, nil
+	}
+	res := []string{}
+	for _, r := range results {
+		if r.Value != nil {
+			if r.Value.StringVal != "" {
+				sName, resultName, err := v1.ExtractStepResultName(r.Value.StringVal)
+				if err != nil {
+					return nil, err
+				}
+				if stepName == sName {
+					res = append(res, resultName)
+				}
+			}
+		}
+	}
+	// No step results need fetching
+	if len(res) == 0 {
+		return nil, nil
+	}
+	return []string{"-step_results", strings.Join(res, ",")}, nil
+}
+
 func resultArgument(steps []corev1.Container, results []v1.TaskResult) []string {
 	if len(results) == 0 {
 		return nil
@@ -209,7 +253,9 @@ func resultArgument(steps []corev1.Container, results []v1.TaskResult) []string
 func collectResultsName(results []v1.TaskResult) string {
 	var resultNames []string
 	for _, r := range results {
-		resultNames = append(resultNames, r.Name)
+		if r.Value == nil {
+			resultNames = append(resultNames, r.Name)
+		}
 	}
 	return strings.Join(resultNames, ",")
 }
@@ -318,14 +364,14 @@ func IsSidecarStatusRunning(tr *v1.TaskRun) bool {
 
 // IsContainerStep returns true if the container name indicates that it
 // represents a step.
-func IsContainerStep(name string) bool { return strings.HasPrefix(name, stepPrefix) }
+func IsContainerStep(name string) bool { return strings.HasPrefix(name, StepPrefix) }
 
 // isContainerSidecar returns true if the container name indicates that it
 // represents a sidecar.
 func isContainerSidecar(name string) bool { return strings.HasPrefix(name, sidecarPrefix) }
 
 // trimStepPrefix returns the container name, stripped of its step prefix.
-func trimStepPrefix(name string) string { return strings.TrimPrefix(name, stepPrefix) }
+func trimStepPrefix(name string) string { return strings.TrimPrefix(name, StepPrefix) }
 
 // TrimSidecarPrefix returns the container name, stripped of its sidecar
 // prefix.
@@ -335,7 +381,7 @@ func TrimSidecarPrefix(name string) string { return strings.TrimPrefix(name, sid
 // returns "step-unnamed-<step-index>" if not specified
 func StepName(name string, i int) string {
 	if name != "" {
-		return fmt.Sprintf("%s%s", stepPrefix, name)
+		return fmt.Sprintf("%s%s", StepPrefix, name)
 	}
-	return fmt.Sprintf("%sunnamed-%d", stepPrefix, i)
+	return fmt.Sprintf("%sunnamed-%d", StepPrefix, i)
 }