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

@@ -59,6 +59,8 @@ var (
 	enableSpire            = flag.Bool("enable_spire", false, "If specified by configmap, this enables spire signing and verification")
 	socketPath             = flag.String("spire_socket_path", "unix:///spiffe-workload-api/spire-agent.sock", "Experimental: The SPIRE agent socket for SPIFFE workload API.")
 	resultExtractionMethod = flag.String("result_from", featureFlags.ResultExtractionMethodTerminationMessage, "The method using which to extract results from tasks. Default is using the termination message.")
+	stepName               = flag.String("step_name", "", "Name of the step")
+	stepResults            = flag.String("step_results", "", "step results if specified")
 )
 
 const (
@@ -145,6 +147,13 @@ func main() {
 		}
 		spireWorkloadAPI = spire.NewEntrypointerAPIClient(&spireConfig)
 	}
+	stepRes := map[string]string{}
+	if *stepResults != "" {
+		err := json.Unmarshal([]byte(*stepResults), &stepRes)
+		if err != nil {
+			log.Fatal(err)
+		}
+	}
 
 	e := entrypoint.Entrypointer{
 		Command:         append(cmd, commandArgs...),
@@ -159,11 +168,13 @@ func main() {
 		},
 		PostWriter:             &realPostWriter{},
 		Results:                strings.Split(*results, ","),
+		StepResults:            stepRes,
 		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,88 @@ 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` 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
+```
+
+All results produced by the `Steps` are automatically surfaced to the `Task`. This means that unless there are name conflicts between `StepActions` in the same `Task`, the `Task` can rely on the name of the result in the `StepAction`. Only if there is a name conflict, does the Task need to explicitly specify the `value` field.
+
+For example, lets assume that in the previous example, the "kaniko" `StepAction` also produced a result called "digest". In that case, the `Task` could simply declare a result "digest" instead of mapping it to something else. The `value` from the "kaniko" `StepAction` would be auto-surfaced.
+
+```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" 
+  steps:
+    - name: git-clone
+      ref:
+        name: clone-step-action
+    - name: kaniko
+      ref:
+        name: kaniko-step-action
+```
+
+However, in the above examples, if the `result` "url" was not resolved by the `Task` to "git-url" and "registry-url", and instead the `Task` just specified "url", the value surfaced to it could be either the "url" from the "kaniko-step-action" `StepAction` or "clone-step-action". **In case of name conflicts, always resolve the result produced by the underlying StepActions.**
+
+
+
 ### 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 map[string]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(pipeline.StepsDir, e.StepName, "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) > 0 {
 		resultPath := pipeline.DefaultResultPath
 		if e.ResultsDirectory != "" {
 			resultPath = e.ResultsDirectory
@@ -264,6 +273,20 @@ func (e Entrypointer) readResultsFromDisk(ctx context.Context, resultDir string)
 			ResultType: result.TaskRunResultType,
 		})
 	}
+	for resultName, resultPath := range e.StepResults {
+		fileContents, err := os.ReadFile(resultPath)
+		if os.IsNotExist(err) {
+			continue
+		} else if err != nil {
+			return err
+		}
+		// if the file doesn't exist, ignore it
+		output = append(output, result.RunResult{
+			Key:        resultName,
+			Value:      string(fileContents),
+			ResultType: result.TaskRunResultType,
+		})
+	}
 	if e.SpireWorkloadAPI != nil {
 		signed, err := e.SpireWorkloadAPI.Sign(ctx, output)
 		if err != nil {

pkg/pod/entrypoint.go

@@ -124,7 +124,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")
 	}
@@ -143,12 +143,17 @@ func orderContainers(commonExtraEntrypointArgs []string, steps []corev1.Containe
 		} else { // Not the first step - wait for previous
 			argsForEntrypoint = append(argsForEntrypoint, "-wait_file", filepath.Join(RunDir, strconv.Itoa(i-1), "out"))
 		}
+		stepName := StepName(s.Name, i, false)
 		argsForEntrypoint = append(argsForEntrypoint,
 			// Start next step.
 			"-post_file", filepath.Join(RunDir, idx, "out"),
 			"-termination_path", terminationPath,
 			"-step_metadata_dir", filepath.Join(RunDir, idx, "status"),
 		)
+		if config.FromContextOrDefaults(ctx).FeatureFlags.EnableStepActions {
+			argsForEntrypoint = append(argsForEntrypoint, "-step_name", stepName)
+		}
+
 		argsForEntrypoint = append(argsForEntrypoint, commonExtraEntrypointArgs...)
 		if taskSpec != nil {
 			if taskSpec.Steps != nil && len(taskSpec.Steps) >= i+1 {
@@ -170,6 +175,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, stepName)
+				if err != nil {
+					return nil, err
+				}
+				argsForEntrypoint = append(argsForEntrypoint, stepResultArgs...)
+			}
 		}
 
 		if breakpointConfig != nil && breakpointConfig.NeedsDebugOnFailure() {
@@ -199,6 +211,36 @@ 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 := map[string]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[r.Name] = filepath.Join(pipeline.StepsDir, stepName, "results", resultName)
+				}
+			}
+		} else {
+			res[r.Name] = filepath.Join(pipeline.StepsDir, stepName, "results", r.Name)
+		}
+	}
+	resBytes, err := json.Marshal(res)
+	if err != nil {
+		return nil, err
+	}
+	return []string{"-step_results", string(resBytes)}, nil
+}
+
 func resultArgument(steps []corev1.Container, results []v1.TaskResult) []string {
 	if len(results) == 0 {
 		return nil
@@ -209,7 +251,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, ",")
 }
@@ -333,9 +377,13 @@ func TrimSidecarPrefix(name string) string { return strings.TrimPrefix(name, sid
 
 // StepName returns the step name after adding "step-" prefix to the actual step name or
 // returns "step-unnamed-<step-index>" if not specified
-func StepName(name string, i int) string {
+func StepName(name string, i int, addPrefix bool) string {
+	prefix := ""
+	if addPrefix {
+		prefix = stepPrefix
+	}
 	if name != "" {
-		return fmt.Sprintf("%s%s", stepPrefix, name)
+		return fmt.Sprintf("%s%s", prefix, name)
 	}
-	return fmt.Sprintf("%sunnamed-%d", stepPrefix, i)
+	return fmt.Sprintf("%sunnamed-%d", prefix, i)
 }