Introduce StepAction referencing syntax in Steps

This PR adds the referencing syntax for `StepActions` in `Stpes`. It also adds the necessary conversion between `v1beta1` and `v1` and the necessary validation.
tektoncd · Oct 26, 2023 · f96950d · f96950d
1 parent 08ee164
commit f96950d
Show file tree

Hide file tree

Showing 16 changed files with 716 additions and 15 deletions.
diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -3270,6 +3270,35 @@ github.com/tektoncd/pipeline/pkg/apis/config.FeatureFlags
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1.Ref">Ref
+</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1.Step">Step</a>)
+</p>
+<div>
+<p>Ref can be used to refer to a specific instance of a StepAction.</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 of the referenced step</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="tekton.dev/v1.RefSource">RefSource
 </h3>
 <p>
@@ -4353,6 +4382,20 @@ StepOutputConfig
 <p>Stores configuration for the stderr stream of the step.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>ref</code><br/>
+<em>
+<a href="#tekton.dev/v1.Ref">
+Ref
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Contains the reference to an existing StepAction.</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.StepOutputConfig">StepOutputConfig
@@ -11758,6 +11801,35 @@ github.com/tektoncd/pipeline/pkg/apis/config.FeatureFlags
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1beta1.Ref">Ref
+</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.Step">Step</a>)
+</p>
+<div>
+<p>Ref can be used to refer to a specific instance of a StepAction.</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 of the referenced step</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="tekton.dev/v1beta1.RefSource">RefSource
 </h3>
 <p>
@@ -12954,6 +13026,20 @@ StepOutputConfig
 <p>Stores configuration for the stderr stream of the step.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>ref</code><br/>
+<em>
+<a href="#tekton.dev/v1beta1.Ref">
+Ref
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Contains the reference to an existing StepAction.</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1beta1.StepOutputConfig">StepOutputConfig

diff --git a/docs/stepactions.md b/docs/stepactions.md
@@ -52,5 +52,86 @@ spec:
       value: /home
   image: ubuntu 
   command: ["ls"]
-  args:: ["-lh"]
+  args: ["-lh"]
+```
+
+## Referencing a StepAction
+
+`StepActions` can be referenced from the `Step` using the `ref` field, as follows:
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    steps:
+      - name: action-runner
+        ref:
+          name: step-action
+```
+
+If a `Step` is referencing a `StepAction`, it cannot contain the fields supported by `StepActions`. This includes:
+- `image`
+- `command`
+- `args`
+- `script`
+- `env`
+
+Using any of the above fields and referencing a `StepAction` in the same `Step` is not allowed and will cause an validation error.
+
+```yaml
+# This is not allowed and will result in a validation error.
+# Because the image is expected to be provided by the StepAction
+# and not inlined.
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    steps:
+      - name: action-runner
+        ref:
+          name: step-action
+        image: ubuntu
+```
+Executing the above `TaskRun` will result in an error that looks like:
+
+```
+Error from server (BadRequest): error when creating "STDIN": admission webhook "validation.webhook.pipeline.tekton.dev" denied the request: validation failed: image cannot be used with Ref: spec.taskSpec.steps[0].image
+```
+
+When a `Step` is referencing a `StepAction`, it can contain the following fields:
+- `computeResources`
+- `workspaces` (Isolated workspaces)
+- `volumeDevices`
+- `imagePullPolicy`
+- `onError`
+- `stdoutConfig`
+- `stderrConfig`
+- `securityContext`
+- `envFrom`
+- `timeout`
+
+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:
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    steps:
+      - name: action-runner
+        ref:
+          name: step-action
+        computeResources:
+          requests:
+            memory: 1Gi
+            cpu: 500m
+        timeout: 1h
+        onError: continue
 ```
diff --git a/pkg/apis/pipeline/v1/container_types.go b/pkg/apis/pipeline/v1/container_types.go
@@ -135,6 +135,15 @@ type Step struct {
 	// Stores configuration for the stderr stream of the step.
 	// +optional
 	StderrConfig *StepOutputConfig `json:"stderrConfig,omitempty"`
+	// Contains the reference to an existing StepAction.
+	//+optional
+	Ref *Ref `json:"ref,omitempty"`
+}
+
+// Ref can be used to refer to a specific instance of a StepAction.
+type Ref struct {
+	// Name of the referenced step
+	Name string `json:"name,omitempty"`
 }
 
 // OnErrorType defines a list of supported exiting behavior of a container on error

diff --git a/pkg/apis/pipeline/v1/openapi_generated.go b/pkg/apis/pipeline/v1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -1093,6 +1093,16 @@
         }
       }
     },
+    "v1.Ref": {
+      "description": "Ref can be used to refer to a specific instance of a StepAction.",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Name of the referenced step",
+          "type": "string"
+        }
+      }
+    },
     "v1.RefSource": {
       "description": "RefSource contains the information that can uniquely identify where a remote built definition came from i.e. Git repositories, Tekton Bundles in OCI registry and hub.",
       "type": "object",
@@ -1445,6 +1455,10 @@
           "description": "OnError defines the exiting behavior of a container on error can be set to [ continue | stopAndFail ]",
           "type": "string"
         },
+        "ref": {
+          "description": "Contains the reference to an existing StepAction.",
+          "$ref": "#/definitions/v1.Ref"
+        },
         "script": {
           "description": "Script is the contents of an executable file to execute.\n\nIf Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.",
           "type": "string"

diff --git a/pkg/apis/pipeline/v1/task_validation.go b/pkg/apis/pipeline/v1/task_validation.go
@@ -264,17 +264,53 @@ func validateSteps(ctx context.Context, steps []Step) (errs *apis.FieldError) {
 }
 
 func validateStep(ctx context.Context, s Step, names sets.String) (errs *apis.FieldError) {
-	if s.Image == "" {
-		errs = errs.Also(apis.ErrMissingField("Image"))
-	}
-
-	if s.Script != "" {
+	if s.Ref != nil {
+		if !config.FromContextOrDefaults(ctx).FeatureFlags.EnableStepActions {
+			return apis.ErrGeneric("feature flag %s should be set to true to reference StepActions in Steps.", config.EnableStepActions)
+		}
+		if s.Image != "" {
+			errs = errs.Also(&apis.FieldError{
+				Message: "image cannot be used with Ref",
+				Paths:   []string{"image"},
+			})
+		}
 		if len(s.Command) > 0 {
 			errs = errs.Also(&apis.FieldError{
-				Message: "script cannot be used with command",
+				Message: "command cannot be used with Ref",
+				Paths:   []string{"command"},
+			})
+		}
+		if len(s.Args) > 0 {
+			errs = errs.Also(&apis.FieldError{
+				Message: "args cannot be used with Ref",
+				Paths:   []string{"args"},
+			})
+		}
+		if s.Script != "" {
+			errs = errs.Also(&apis.FieldError{
+				Message: "script cannot be used with Ref",
 				Paths:   []string{"script"},
 			})
 		}
+		if s.Env != nil {
+			errs = errs.Also(&apis.FieldError{
+				Message: "env cannot be used with Ref",
+				Paths:   []string{"env"},
+			})
+		}
+	} else {
+		if s.Image == "" {
+			errs = errs.Also(apis.ErrMissingField("Image"))
+		}
+
+		if s.Script != "" {
+			if len(s.Command) > 0 {
+				errs = errs.Also(&apis.FieldError{
+					Message: "script cannot be used with command",
+					Paths:   []string{"script"},
+				})
+			}
+		}
 	}
 
 	if s.Name != "" {