Referencing StepActions in Steps

This PR allows the Step to reference a StepAction CRD deployed on the cluster. This capability is gated behind a feature flag `enable-step-actions`.  Remote resolution of StepActions will be implemented in a follow-up PR.

This is the second item on the implementation Issue tektoncd#7259

config/config-feature-flags.yaml

@@ -124,3 +124,6 @@ data:
   # Setting this flag to "true" will enable the CEL evaluation in WhenExpression
   # This feature is in preview mode and not implemented yet. Please check #7244 for the updates.
   enable-cel-in-whenexpression: "false"
+  # Setting this flag to "true" will enable the use of StepActions in Steps
+  # This feature is in preview mode and not implemented yet. Please check #7259 for updates.
+  enable-step-actions: "false"

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

docs/stepactions.md

@@ -54,3 +54,87 @@ spec:
   command: ["ls"]
   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
+```
+
+Upon resolution and execution of the `TaskRun`, the `Status` will look something like:
+
+```yaml
+status:
+  completionTime: "2023-10-24T20:28:42Z"
+  conditions:
+  - lastTransitionTime: "2023-10-24T20:28:42Z"
+    message: All Steps have completed executing
+    reason: Succeeded
+    status: "True"
+    type: Succeeded
+  podName: step-action-run-pod
+  provenance:
+    featureFlags:
+      EnableStepActions: true
+      ...
+  startTime: "2023-10-24T20:28:32Z"
+  steps:
+  - container: step-action-runner
+    imageID: docker.io/library/alpine@sha256:eece025e432126ce23f223450a0326fbebde39cdf496a85d8c016293fc851978
+    name: action-runner
+    terminated:
+      containerID: containerd://46a836588967202c05b594696077b147a0eb0621976534765478925bb7ce57f6
+      exitCode: 0
+      finishedAt: "2023-10-24T20:28:42Z"
+      reason: Completed
+      startedAt: "2023-10-24T20:28:42Z"
+  taskSpec:
+    steps:
+    - computeResources: {}
+      image: alpine
+      name: action-runner
+      script: |
+        echo "I am a 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
+```

examples/v1/taskruns/alpha/stepaction.yaml

@@ -0,0 +1,19 @@
+apiVersion: tekton.dev/v1alpha1
+kind: StepAction
+metadata:
+  name: step-action
+spec:
+  image: alpine
+  script: |
+    echo "I am a Step Action!!!"
+---
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: step-action-run
+spec:
+  TaskSpec:
+    steps:
+      - name: action-runner
+        ref:
+          name: step-action

pkg/apis/config/feature_flags.go

@@ -96,6 +96,10 @@ const (
 	EnableCELInWhenExpression = "enable-cel-in-whenexpression"
 	// DefaultEnableCELInWhenExpression is the default value for EnableCELInWhenExpression
 	DefaultEnableCELInWhenExpression = false
+	// EnableStepActions is the flag to enable the use of StepActions in Steps
+	EnableStepActions = "enable-step-actions"
+	// DefaultEnableStepActions is the default value for EnableStepActions
+	DefaultEnableStepActions = false
 
 	disableAffinityAssistantKey         = "disable-affinity-assistant"
 	disableCredsInitKey                 = "disable-creds-init"
@@ -145,6 +149,7 @@ type FeatureFlags struct {
 	SetSecurityContext        bool
 	Coschedule                string
 	EnableCELInWhenExpression bool
+	EnableStepActions         bool
 }
 
 // GetFeatureFlagsConfigName returns the name of the configmap containing all
@@ -220,6 +225,9 @@ func NewFeatureFlagsFromMap(cfgMap map[string]string) (*FeatureFlags, error) {
 	if err := setFeature(EnableCELInWhenExpression, DefaultEnableCELInWhenExpression, &tc.EnableCELInWhenExpression); err != nil {
 		return nil, err
 	}
+	if err := setFeature(EnableStepActions, DefaultEnableStepActions, &tc.EnableStepActions); err != nil {
+		return nil, err
+	}
 	// Given that they are alpha features, Tekton Bundles and Custom Tasks should be switched on if
 	// enable-api-fields is "alpha". If enable-api-fields is not "alpha" then fall back to the value of
 	// each feature's individual flag.

pkg/apis/config/feature_flags_test.go

@@ -74,6 +74,7 @@ func TestNewFeatureFlagsFromConfigMap(t *testing.T) {
 				SetSecurityContext:               true,
 				Coschedule:                       config.CoscheduleDisabled,
 				EnableCELInWhenExpression:        true,
+				EnableStepActions:                true,
 			},
 			fileName: "feature-flags-all-flags-set",
 		},
@@ -273,6 +274,9 @@ func TestNewFeatureFlagsConfigMapErrors(t *testing.T) {
 	}, {
 		fileName: "feature-flags-invalid-enable-cel-in-whenexpression",
 		want:     `failed parsing feature flags config "invalid": strconv.ParseBool: parsing "invalid": invalid syntax`,
+	}, {
+		fileName: "feature-flags-invalid-enable-step-actions",
+		want:     `failed parsing feature flags config "invalid": strconv.ParseBool: parsing "invalid": invalid syntax`,
 	}} {
 		t.Run(tc.fileName, func(t *testing.T) {
 			cm := test.ConfigMapFromTestFile(t, tc.fileName)

pkg/apis/config/testdata/feature-flags-all-flags-set.yaml

@@ -33,3 +33,4 @@ data:
   set-security-context: "true"
   keep-pod-on-cancel: "true"
   enable-cel-in-whenexpression: "true"
+  enable-step-actions: "true"

pkg/apis/config/testdata/feature-flags-invalid-enable-step-actions.yaml

@@ -0,0 +1,21 @@
+# Copyright 2023 The Tekton Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: feature-flags
+  namespace: tekton-pipelines
+data:
+  enable-step-actions: "invalid"

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