Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

TEP-0142: Introduce Params and Results into StepActions CRD #7317

Merged
merged 1 commit into from
Nov 3, 2023
Merged

TEP-0142: Introduce Params and Results into StepActions CRD #7317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
134 changes: 131 additions & 3 deletions docs/pipeline-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand Down
58 changes: 58 additions & 0 deletions docs/stepactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions hack/ignored-openapi-violations.list
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions pkg/apis/pipeline/v1/param_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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))
}
Expand Down