Skip to content

Commit 695311e

Browse files
chitrangpateltekton-robot
chitrangpatel
authored and
tekton-robot
committed
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`.
1 parent a791d49 commit 695311e

18 files changed

+1620
-30
lines changed

‎docs/pipeline-api.md‎

Lines changed: 131 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1709,7 +1709,7 @@ If Enum is not set, no input validation is performed for the param.</p>
17091709
<h3 id="tekton.dev/v1.ParamSpecs">ParamSpecs
17101710
(<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.ParamSpec</code> alias)</h3>
17111711
<p>
1712-
(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineSpec">PipelineSpec</a>, <a href="#tekton.dev/v1.TaskSpec">TaskSpec</a>)
1712+
(<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>)
17131713
</p>
17141714
<div>
17151715
<p>ParamSpecs is a list of ParamSpec</p>
@@ -3214,7 +3214,7 @@ this field is false and so declared workspaces are required.</p>
32143214
<h3 id="tekton.dev/v1.PropertySpec">PropertySpec
32153215
</h3>
32163216
<p>
3217-
(<em>Appears on:</em><a href="#tekton.dev/v1.ParamSpec">ParamSpec</a>, <a href="#tekton.dev/v1.TaskResult">TaskResult</a>)
3217+
(<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>)
32183218
</p>
32193219
<div>
32203220
<p>PropertySpec defines the struct for object keys</p>
@@ -3506,7 +3506,7 @@ string
35063506
<h3 id="tekton.dev/v1.ResultsType">ResultsType
35073507
(<code>string</code> alias)</h3>
35083508
<p>
3509-
(<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>)
3509+
(<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>)
35103510
</p>
35113511
<div>
35123512
<p>ResultsType indicates the type of a result;
@@ -6569,6 +6569,35 @@ string
65696569
<p>If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.</p>
65706570
</td>
65716571
</tr>
6572+
<tr>
6573+
<td>
6574+
<code>params</code><br/>
6575+
<em>
6576+
<a href="#tekton.dev/v1.ParamSpecs">
6577+
ParamSpecs
6578+
</a>
6579+
</em>
6580+
</td>
6581+
<td>
6582+
<em>(Optional)</em>
6583+
<p>Params is a list of input parameters required to run the stepAction.
6584+
Params must be supplied as inputs in Steps unless they declare a defaultvalue.</p>
6585+
</td>
6586+
</tr>
6587+
<tr>
6588+
<td>
6589+
<code>results</code><br/>
6590+
<em>
6591+
<a href="#tekton.dev/v1alpha1.StepActionResult">
6592+
[]StepActionResult
6593+
</a>
6594+
</em>
6595+
</td>
6596+
<td>
6597+
<em>(Optional)</em>
6598+
<p>Results are values that this StepAction can output</p>
6599+
</td>
6600+
</tr>
65726601
</table>
65736602
</td>
65746603
</tr>
@@ -7234,6 +7263,76 @@ Refer Go&rsquo;s ParseDuration documentation for expected format: <a href="https
72347263
<div>
72357264
<p>StepActionObject is implemented by StepAction</p>
72367265
</div>
7266+
<h3 id="tekton.dev/v1alpha1.StepActionResult">StepActionResult
7267+
</h3>
7268+
<p>
7269+
(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.StepActionSpec">StepActionSpec</a>)
7270+
</p>
7271+
<div>
7272+
<p>StepActionResult used to describe the results of a task</p>
7273+
</div>
7274+
<table>
7275+
<thead>
7276+
<tr>
7277+
<th>Field</th>
7278+
<th>Description</th>
7279+
</tr>
7280+
</thead>
7281+
<tbody>
7282+
<tr>
7283+
<td>
7284+
<code>name</code><br/>
7285+
<em>
7286+
string
7287+
</em>
7288+
</td>
7289+
<td>
7290+
<p>Name the given name</p>
7291+
</td>
7292+
</tr>
7293+
<tr>
7294+
<td>
7295+
<code>type</code><br/>
7296+
<em>
7297+
<a href="#tekton.dev/v1.ResultsType">
7298+
ResultsType
7299+
</a>
7300+
</em>
7301+
</td>
7302+
<td>
7303+
<em>(Optional)</em>
7304+
<p>Type is the user-specified type of the result. The possible type
7305+
is currently &ldquo;string&rdquo; and will support &ldquo;array&rdquo; in following work.</p>
7306+
</td>
7307+
</tr>
7308+
<tr>
7309+
<td>
7310+
<code>properties</code><br/>
7311+
<em>
7312+
<a href="#tekton.dev/v1.PropertySpec">
7313+
map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PropertySpec
7314+
</a>
7315+
</em>
7316+
</td>
7317+
<td>
7318+
<em>(Optional)</em>
7319+
<p>Properties is the JSON Schema properties to support key-value pairs results.</p>
7320+
</td>
7321+
</tr>
7322+
<tr>
7323+
<td>
7324+
<code>description</code><br/>
7325+
<em>
7326+
string
7327+
</em>
7328+
</td>
7329+
<td>
7330+
<em>(Optional)</em>
7331+
<p>Description is a human-readable description of the result</p>
7332+
</td>
7333+
</tr>
7334+
</tbody>
7335+
</table>
72377336
<h3 id="tekton.dev/v1alpha1.StepActionSpec">StepActionSpec
72387337
</h3>
72397338
<p>
@@ -7329,6 +7428,35 @@ string
73297428
<p>If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.</p>
73307429
</td>
73317430
</tr>
7431+
<tr>
7432+
<td>
7433+
<code>params</code><br/>
7434+
<em>
7435+
<a href="#tekton.dev/v1.ParamSpecs">
7436+
ParamSpecs
7437+
</a>
7438+
</em>
7439+
</td>
7440+
<td>
7441+
<em>(Optional)</em>
7442+
<p>Params is a list of input parameters required to run the stepAction.
7443+
Params must be supplied as inputs in Steps unless they declare a defaultvalue.</p>
7444+
</td>
7445+
</tr>
7446+
<tr>
7447+
<td>
7448+
<code>results</code><br/>
7449+
<em>
7450+
<a href="#tekton.dev/v1alpha1.StepActionResult">
7451+
[]StepActionResult
7452+
</a>
7453+
</em>
7454+
</td>
7455+
<td>
7456+
<em>(Optional)</em>
7457+
<p>Results are values that this StepAction can output</p>
7458+
</td>
7459+
</tr>
73327460
</tbody>
73337461
</table>
73347462
<h3 id="tekton.dev/v1alpha1.VerificationPolicySpec">VerificationPolicySpec

‎docs/stepactions.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ A `StepAction` definition supports the following fields:
3838
- `script`
3939
- cannot be used at the same time as using `command`.
4040
- `env`
41+
- [`params`](#declaring-params)
42+
- [`results`](#declaring-results)
4143

4244
The non-functional example below demonstrates the use of most of the above-mentioned fields:
4345

@@ -55,6 +57,62 @@ spec:
5557
args: ["-lh"]
5658
```
5759
60+
### Declaring Parameters
61+
62+
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`.
63+
64+
`Parameters` are passed to the `StepAction` from its corresponding `Step` referencing it.
65+
66+
```yaml
67+
apiVersion: tekton.dev/v1alpha1
68+
kind: StepAction
69+
metadata:
70+
name: stepaction-using-params
71+
spec:
72+
params:
73+
- name: gitrepo
74+
type: object
75+
properties:
76+
url:
77+
type: string
78+
commit:
79+
type: string
80+
- name: flags
81+
type: array
82+
- name: outputPath
83+
type: string
84+
default: "/workspace"
85+
image: some-git-image
86+
args: [
87+
"-url=$(params.gitrepo.url)",
88+
"-revision=$(params.gitrepo.commit)",
89+
"-output=$(params.outputPath)",
90+
"$(params.flags[*])",
91+
]
92+
```
93+
94+
### Declaring Results
95+
96+
A `StepAction` also declares the results that it will emit.
97+
98+
```yaml
99+
apiVersion: tekton.dev/v1alpha1
100+
kind: StepAction
101+
metadata:
102+
name: stepaction-declaring-results
103+
spec:
104+
results:
105+
- name: current-date-unix-timestamp
106+
description: The current date in unix timestamp format
107+
- name: current-date-human-readable
108+
description: The current date in human readable format
109+
image: bash:latest
110+
script: |
111+
#!/usr/bin/env bash
112+
date +%s | tee $(results.current-date-unix-timestamp.path)
113+
date | tee $(results.current-date-human-readable.path)
114+
```
115+
58116
## Referencing a StepAction
59117

60118
`StepActions` can be referenced from the `Step` using the `ref` field, as follows:

‎hack/ignored-openapi-violations.list‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v
3838
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepTemplate,DeprecatedTerminationMessagePath
3939
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,StepTemplate,DeprecatedTerminationMessagePolicy
4040
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/resolution/v1alpha1,ResolutionRequestSpec,Parameters
41+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,ArrayVal
42+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,ObjectVal
43+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,StringVal
44+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,ParamValue,Type
45+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,StepActionSpec,Params
46+
API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,StepActionSpec,Results
4147
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,RunSpec,Workspaces
4248
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Authorities
4349
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Resources

‎pkg/apis/pipeline/v1/param_types.go‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -108,17 +108,17 @@ func (pp *ParamSpec) setDefaultsForProperties() {
108108
}
109109
}
110110

111-
// getNames returns all the names of the declared parameters
112-
func (ps ParamSpecs) getNames() []string {
111+
// GetNames returns all the names of the declared parameters
112+
func (ps ParamSpecs) GetNames() []string {
113113
var names []string
114114
for _, p := range ps {
115115
names = append(names, p.Name)
116116
}
117117
return names
118118
}
119119

120-
// sortByType splits the input params into string params, array params, and object params, in that order
121-
func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
120+
// SortByType splits the input params into string params, array params, and object params, in that order
121+
func (ps ParamSpecs) SortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
122122
var stringParams, arrayParams, objectParams ParamSpecs
123123
for _, p := range ps {
124124
switch p.Type {
@@ -135,10 +135,10 @@ func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
135135
return stringParams, arrayParams, objectParams
136136
}
137137

138-
// validateNoDuplicateNames returns an error if any of the params have the same name
139-
func (ps ParamSpecs) validateNoDuplicateNames() *apis.FieldError {
138+
// ValidateNoDuplicateNames returns an error if any of the params have the same name
139+
func (ps ParamSpecs) ValidateNoDuplicateNames() *apis.FieldError {
140140
var errs *apis.FieldError
141-
names := ps.getNames()
141+
names := ps.GetNames()
142142
for dup := range findDups(names) {
143143
errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", dup))
144144
}

0 commit comments

Comments
 (0)