Skip to content

Commit

Permalink
TEP-0142: Add syntax for providing params to StepActions
Browse files Browse the repository at this point in the history
Following the previous [PR](tektoncd#7317), which introduced Params to the `StepAction` CRD,
this PR integrates `param` usage between `Steps` and `StepActions`. This PR adds the necessary syntax to `Steps` to pass `params` to `StepActions`. This work is part of
issue tektoncd#7259.
  • Loading branch information
chitrangpatel committed Nov 6, 2023
1 parent 695311e commit a8e1e14
Show file tree
Hide file tree
Showing 16 changed files with 214 additions and 4 deletions.
32 changes: 30 additions & 2 deletions docs/pipeline-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1802,7 +1802,7 @@ map[string]string
<h3 id="tekton.dev/v1.Params">Params
(<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Param</code> alias)</h3>
<p>
(<em>Appears on:</em><a href="#tekton.dev/v1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1.Matrix">Matrix</a>, <a href="#tekton.dev/v1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1.TaskRunSpec">TaskRunSpec</a>)
(<em>Appears on:</em><a href="#tekton.dev/v1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1.Matrix">Matrix</a>, <a href="#tekton.dev/v1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1.Step">Step</a>, <a href="#tekton.dev/v1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1.TaskRunSpec">TaskRunSpec</a>)
</p>
<div>
<p>Params is a list of Param</p>
Expand Down Expand Up @@ -4427,6 +4427,20 @@ Ref
<p>Contains the reference to an existing StepAction.</p>
</td>
</tr>
<tr>
<td>
<code>params</code><br/>
<em>
<a href="#tekton.dev/v1.Params">
Params
</a>
</em>
</td>
<td>
<em>(Optional)</em>
<p>Params declares parameters passed to this step action.</p>
</td>
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1.StepOutputConfig">StepOutputConfig
Expand Down Expand Up @@ -10215,7 +10229,7 @@ map[string]string
<h3 id="tekton.dev/v1beta1.Params">Params
(<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param</code> alias)</h3>
<p>
(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>)
(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.Step">Step</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>)
</p>
<div>
<p>Params is a list of Param</p>
Expand Down Expand Up @@ -13227,6 +13241,20 @@ Ref
<p>Contains the reference to an existing StepAction.</p>
</td>
</tr>
<tr>
<td>
<code>params</code><br/>
<em>
<a href="#tekton.dev/v1beta1.Params">
Params
</a>
</em>
</td>
<td>
<em>(Optional)</em>
<p>Params declares parameters passed to this step action.</p>
</td>
</tr>
</tbody>
</table>
<h3 id="tekton.dev/v1beta1.StepOutputConfig">StepOutputConfig
Expand Down
31 changes: 31 additions & 0 deletions docs/stepactions.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,8 @@ When a `Step` is referencing a `StepAction`, it can contain the following fields
- `securityContext`
- `envFrom`
- `timeout`
- `ref`
- `params`

Using any of the above fields and referencing a `StepAction` is allowed and will not cause an error. For example, the `TaskRun` below will execute without any errors:

Expand All @@ -220,10 +222,39 @@ spec:
- name: action-runner
ref:
name: step-action
params:
- name: step-action-param
value: hello
computeResources:
requests:
memory: 1Gi
cpu: 500m
timeout: 1h
onError: continue
```

### Passing Params to StepAction

A `StepAction` may require [params](#(declaring-parameters)). In this case, a `Task` needs to ensure that the `StepAction` has access to all the required `params`.
When referencing a `StepAction`, a `Step` can also provide it with `params`, just like how a `TaskRun` provides params to the underlying `Task`.

```yaml
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: step-action
spec:
TaskSpec:
params:
- name: param-for-step-action
description: "this is a param that the step action needs."
steps:
- name: action-runner
ref:
name: step-action
params:
- name: step-action-param
value: $(params.param-for-step-action)
```

**Note:** If a `Step` declares `params` for an `inlined Step`, it will also lead to a validation error. This is because an `inlined Step` gets it's `params` from the `TaskRun`.
4 changes: 4 additions & 0 deletions pkg/apis/pipeline/v1/container_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@ type Step struct {
// Contains the reference to an existing StepAction.
//+optional
Ref *Ref `json:"ref,omitempty"`
// Params declares parameters passed to this step action.
// +optional
// +listType=atomic
Params Params `json:"params,omitempty"`
}

// Ref can be used to refer to a specific instance of a StepAction.
Expand Down
21 changes: 20 additions & 1 deletion pkg/apis/pipeline/v1/openapi_generated.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 9 additions & 0 deletions pkg/apis/pipeline/v1/swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -1463,6 +1463,15 @@
"description": "OnError defines the exiting behavior of a container on error can be set to [ continue | stopAndFail ]",
"type": "string"
},
"params": {
"description": "Params declares parameters passed to this step action.",
"type": "array",
"items": {
"default": {},
"$ref": "#/definitions/v1.Param"
},
"x-kubernetes-list-type": "atomic"
},
"ref": {
"description": "Contains the reference to an existing StepAction.",
"$ref": "#/definitions/v1.Ref"
Expand Down
6 changes: 6 additions & 0 deletions pkg/apis/pipeline/v1/task_validation.go
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,12 @@ func validateStep(ctx context.Context, s Step, names sets.String) (errs *apis.Fi
})
}
} else {
if len(s.Params) > 0 {
errs = errs.Also(&apis.FieldError{
Message: "params cannot be used without Ref",
Paths: []string{"params"},
})
}
if s.Image == "" {
errs = errs.Also(apis.ErrMissingField("Image"))
}
Expand Down
23 changes: 23 additions & 0 deletions pkg/apis/pipeline/v1/task_validation_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -534,6 +534,16 @@ func TestTaskSpecStepActionReferenceValidate(t *testing.T) {
Name: "stepAction",
},
}},
}, {
name: "valid use of params with Ref",
Steps: []v1.Step{{
Ref: &v1.Ref{
Name: "stepAction",
},
Params: v1.Params{{
Name: "param",
}},
}},
}}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
Expand Down Expand Up @@ -1490,6 +1500,19 @@ func TestTaskSpecValidateErrorWithStepActionRef(t *testing.T) {
Message: "env cannot be used with Ref",
Paths: []string{"steps[0].env"},
},
}, {
name: "Cannot use params without Ref",
Steps: []v1.Step{{
Image: "my-image",
Params: v1.Params{{
Name: "param",
}},
}},
enableStepActions: true,
expectedError: apis.FieldError{
Message: "params cannot be used without Ref",
Paths: []string{"steps[0].params"},
},
}}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
Expand Down
7 changes: 7 additions & 0 deletions pkg/apis/pipeline/v1/zz_generated.deepcopy.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions pkg/apis/pipeline/v1beta1/container_conversion.go
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,12 @@ func (s Step) convertTo(ctx context.Context, sink *v1.Step) {
sink.Ref = &v1.Ref{}
s.Ref.convertTo(ctx, sink.Ref)
}
sink.Params = nil
for _, p := range s.Params {
new := v1.Param{}
p.convertTo(ctx, &new)
sink.Params = append(sink.Params, new)
}
}

func (s *Step) convertFrom(ctx context.Context, source v1.Step) {
Expand Down Expand Up @@ -97,6 +103,12 @@ func (s *Step) convertFrom(ctx context.Context, source v1.Step) {
newRef.convertFrom(ctx, *source.Ref)
s.Ref = &newRef
}
s.Params = nil
for _, p := range source.Params {
new := Param{}
new.ConvertFrom(ctx, p)
s.Params = append(s.Params, new)
}
}

func (s StepTemplate) convertTo(ctx context.Context, sink *v1.StepTemplate) {
Expand Down
4 changes: 4 additions & 0 deletions pkg/apis/pipeline/v1beta1/container_types.go
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,10 @@ type Step struct {
// Contains the reference to an existing StepAction.
//+optional
Ref *Ref `json:"ref,omitempty"`
// Params declares parameters passed to this step action.
// +optional
// +listType=atomic
Params Params `json:"params,omitempty"`
}

// Ref can be used to refer to a specific instance of a StepAction.
Expand Down
21 changes: 20 additions & 1 deletion pkg/apis/pipeline/v1beta1/openapi_generated.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 9 additions & 0 deletions pkg/apis/pipeline/v1beta1/swagger.json
Original file line number Diff line number Diff line change
Expand Up @@ -2070,6 +2070,15 @@
"description": "OnError defines the exiting behavior of a container on error can be set to [ continue | stopAndFail ]",
"type": "string"
},
"params": {
"description": "Params declares parameters passed to this step action.",
"type": "array",
"items": {
"default": {},
"$ref": "#/definitions/v1beta1.Param"
},
"x-kubernetes-list-type": "atomic"
},
"ports": {
"description": "List of ports to expose from the Step's container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default \"0.0.0.0\" address inside a container will be accessible from the network. Cannot be updated.\n\nDeprecated: This field will be removed in a future release.",
"type": "array",
Expand Down
3 changes: 3 additions & 0 deletions pkg/apis/pipeline/v1beta1/task_conversion_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,9 @@ spec:
steps:
- ref:
name: "step-action"
params:
- name: param1
value: hello
`

remoteStepActionTaskYAML := `
Expand Down
6 changes: 6 additions & 0 deletions pkg/apis/pipeline/v1beta1/task_validation.go
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,12 @@ func validateStep(ctx context.Context, s Step, names sets.String) (errs *apis.Fi
})
}
} else {
if len(s.Params) > 0 {
errs = errs.Also(&apis.FieldError{
Message: "params cannot be used without Ref",
Paths: []string{"params"},
})
}
if s.Image == "" {
errs = errs.Also(apis.ErrMissingField("Image"))
}
Expand Down
23 changes: 23 additions & 0 deletions pkg/apis/pipeline/v1beta1/task_validation_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -538,6 +538,16 @@ func TestTaskSpecStepActionReferenceValidate(t *testing.T) {
Name: "stepAction",
},
}},
}, {
name: "valid use of params with Ref",
Steps: []v1beta1.Step{{
Ref: &v1beta1.Ref{
Name: "stepAction",
},
Params: v1beta1.Params{{
Name: "param",
}},
}},
}}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
Expand Down Expand Up @@ -1503,6 +1513,19 @@ func TestTaskSpecValidateErrorWithStepActionRef(t *testing.T) {
Message: "env cannot be used with Ref",
Paths: []string{"steps[0].env"},
},
}, {
name: "Cannot use params without Ref",
Steps: []v1beta1.Step{{
Image: "my-image",
Params: v1beta1.Params{{
Name: "param",
}},
}},
enableStepActions: true,
expectedError: apis.FieldError{
Message: "params cannot be used without Ref",
Paths: []string{"steps[0].params"},
},
}}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
Expand Down
7 changes: 7 additions & 0 deletions pkg/apis/pipeline/v1beta1/zz_generated.deepcopy.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit a8e1e14

Please sign in to comment.