Introduce Params and Results into StepActions CRD

This PR introduces `params` and `results` into the `StepAction` CRD. It allows the `StepAction` to declare the params it needs and the results it will produce. The follow up PRs will contain the interaction of how a `Task` referencing the `StepAction` resolves them. All the tests were borrowed from `pkg/apis/pipeline/v1/...` that overlapped with `paramSpec` and `Results`.
tektoncd · Nov 3, 2023 · 695311e · 695311e
1 parent a791d49
commit 695311e
Show file tree

Hide file tree

Showing 18 changed files with 1,620 additions and 30 deletions.
diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1709,7 +1709,7 @@ If Enum is not set, no input validation is performed for the param.</p>
 <h3 id="tekton.dev/v1.ParamSpecs">ParamSpecs
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.ParamSpec</code> alias)</h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineSpec">PipelineSpec</a>, <a href="#tekton.dev/v1.TaskSpec">TaskSpec</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineSpec">PipelineSpec</a>, <a href="#tekton.dev/v1.TaskSpec">TaskSpec</a>, <a href="#tekton.dev/v1alpha1.StepActionSpec">StepActionSpec</a>)
 </p>
 <div>
 <p>ParamSpecs is a list of ParamSpec</p>
@@ -3214,7 +3214,7 @@ this field is false and so declared workspaces are required.</p>
 <h3 id="tekton.dev/v1.PropertySpec">PropertySpec
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.ParamSpec">ParamSpec</a>, <a href="#tekton.dev/v1.TaskResult">TaskResult</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.ParamSpec">ParamSpec</a>, <a href="#tekton.dev/v1.TaskResult">TaskResult</a>, <a href="#tekton.dev/v1alpha1.StepActionResult">StepActionResult</a>)
 </p>
 <div>
 <p>PropertySpec defines the struct for object keys</p>
@@ -3506,7 +3506,7 @@ string
 <h3 id="tekton.dev/v1.ResultsType">ResultsType
 (<code>string</code> alias)</h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineResult">PipelineResult</a>, <a href="#tekton.dev/v1.TaskResult">TaskResult</a>, <a href="#tekton.dev/v1.TaskRunResult">TaskRunResult</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineResult">PipelineResult</a>, <a href="#tekton.dev/v1.TaskResult">TaskResult</a>, <a href="#tekton.dev/v1.TaskRunResult">TaskRunResult</a>, <a href="#tekton.dev/v1alpha1.StepActionResult">StepActionResult</a>)
 </p>
 <div>
 <p>ResultsType indicates the type of a result;
@@ -6569,6 +6569,35 @@ string
 <p>If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>params</code><br/>
+<em>
+<a href="#tekton.dev/v1.ParamSpecs">
+ParamSpecs
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Params is a list of input parameters required to run the stepAction.
+Params must be supplied as inputs in Steps unless they declare a defaultvalue.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>results</code><br/>
+<em>
+<a href="#tekton.dev/v1alpha1.StepActionResult">
+[]StepActionResult
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Results are values that this StepAction can output</p>
+</td>
+</tr>
 </table>
 </td>
 </tr>
@@ -7234,6 +7263,76 @@ Refer Go&rsquo;s ParseDuration documentation for expected format: <a href="https
 <div>
 <p>StepActionObject is implemented by StepAction</p>
 </div>
+<h3 id="tekton.dev/v1alpha1.StepActionResult">StepActionResult
+</h3>
+<p>
+(<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>
+</div>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>name</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Name the given name</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>type</code><br/>
+<em>
+<a href="#tekton.dev/v1.ResultsType">
+ResultsType
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Type is the user-specified type of the result. The possible type
+is currently &ldquo;string&rdquo; and will support &ldquo;array&rdquo; in following work.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>properties</code><br/>
+<em>
+<a href="#tekton.dev/v1.PropertySpec">
+map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PropertySpec
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Properties is the JSON Schema properties to support key-value pairs results.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>description</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Description is a human-readable description of the result</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="tekton.dev/v1alpha1.StepActionSpec">StepActionSpec
 </h3>
 <p>
@@ -7329,6 +7428,35 @@ string
 <p>If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>params</code><br/>
+<em>
+<a href="#tekton.dev/v1.ParamSpecs">
+ParamSpecs
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Params is a list of input parameters required to run the stepAction.
+Params must be supplied as inputs in Steps unless they declare a defaultvalue.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>results</code><br/>
+<em>
+<a href="#tekton.dev/v1alpha1.StepActionResult">
+[]StepActionResult
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Results are values that this StepAction can output</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1alpha1.VerificationPolicySpec">VerificationPolicySpec

diff --git a/docs/stepactions.md b/docs/stepactions.md
@@ -38,6 +38,8 @@ A `StepAction` definition supports the following fields:
   - `script`
     - cannot be used at the same time as using `command`.
   - `env`
+  - [`params`](#declaring-params)
+  - [`results`](#declaring-results)
 
 The non-functional example below demonstrates the use of most of the above-mentioned fields:
 
@@ -55,6 +57,62 @@ spec:
   args: ["-lh"]
 ```
 
+### Declaring Parameters
+
+Like with `Tasks`, a `StepAction` must declare all the parameters that it used. The same rules for `Parameter` [name](./tasks.md/#parameter-name), [type](./tasks.md/#parameter-type) (including [object](./tasks.md/#object-type), [array](./tasks.md/#array-type) and [string](./tasks.md/#string-type)) apply as when declaring them in `Tasks`. A `StepAction` can also provide [default value](./tasks.md/#default-value) to a `Parameter`. 
+
+ `Parameters` are passed to the `StepAction` from its corresponding `Step` referencing it.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: stepaction-using-params
+spec:
+  params:
+    - name: gitrepo
+      type: object
+      properties:
+        url:
+          type: string
+        commit:
+          type: string
+    - name: flags
+      type: array
+    - name: outputPath
+      type: string
+      default: "/workspace"
+  image: some-git-image
+  args: [
+    "-url=$(params.gitrepo.url)",
+    "-revision=$(params.gitrepo.commit)",
+    "-output=$(params.outputPath)",
+    "$(params.flags[*])",
+  ]
+```
+
+### Declaring Results
+
+A `StepAction` also declares the results that it will emit. 
+
+```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 $(results.current-date-unix-timestamp.path)
+    date | tee $(results.current-date-human-readable.path)
+```
+
 ## Referencing a StepAction
 
 `StepActions` can be referenced from the `Step` using the `ref` field, as follows:

diff --git a/hack/ignored-openapi-violations.list b/hack/ignored-openapi-violations.list
@@ -38,6 +38,12 @@ API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepTemplate,DeprecatedTerminationMessagePath
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepTemplate,DeprecatedTerminationMessagePolicy
 API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/resolution/v1alpha1,ResolutionRequestSpec,Parameters
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,ArrayVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,ObjectVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,StringVal
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,Type
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,StepActionSpec,Params
+API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,StepActionSpec,Results
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,RunSpec,Workspaces
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Authorities
 API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Resources

diff --git a/pkg/apis/pipeline/v1/param_types.go b/pkg/apis/pipeline/v1/param_types.go
@@ -108,17 +108,17 @@ func (pp *ParamSpec) setDefaultsForProperties() {
 	}
 }
 
-// getNames returns all the names of the declared parameters
-func (ps ParamSpecs) getNames() []string {
+// GetNames returns all the names of the declared parameters
+func (ps ParamSpecs) GetNames() []string {
 	var names []string
 	for _, p := range ps {
 		names = append(names, p.Name)
 	}
 	return names
 }
 
-// sortByType splits the input params into string params, array params, and object params, in that order
-func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
+// SortByType splits the input params into string params, array params, and object params, in that order
+func (ps ParamSpecs) SortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
 	var stringParams, arrayParams, objectParams ParamSpecs
 	for _, p := range ps {
 		switch p.Type {
@@ -135,10 +135,10 @@ func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
 	return stringParams, arrayParams, objectParams
 }
 
-// validateNoDuplicateNames returns an error if any of the params have the same name
-func (ps ParamSpecs) validateNoDuplicateNames() *apis.FieldError {
+// ValidateNoDuplicateNames returns an error if any of the params have the same name
+func (ps ParamSpecs) ValidateNoDuplicateNames() *apis.FieldError {
 	var errs *apis.FieldError
-	names := ps.getNames()
+	names := ps.GetNames()
 	for dup := range findDups(names) {
 		errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", dup))
 	}