[TEP-0144] Add enum API field

Part of [tektoncd#7270][tektoncd#7270]. In [TEP-0144][tep-0144] we proposed a new `enum` field to support built-in param input validation.

This commit adds the `Enum` api field, validation and conversion logic.

/kind feature

[tektoncd#7270]: tektoncd#7270
[tep-0144]: https://github.com/tektoncd/community/blob/main/teps/0144-param-enum.md

Author: QuanZhang-William

config/config-feature-flags.yaml

@@ -127,3 +127,6 @@ data:
   # 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"
+  # Setting this flag to "true" will enable the built-in param input validation via param enum.
+  # NOTE (#7270): this feature is still under development and not yet functional.
+  enable-param-enum: "false"

docs/pipeline-api.md

@@ -1691,6 +1691,19 @@ default is set, a Task may be executed without a supplied value for the
 parameter.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>enum</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
+If Enum is not set, no input validation is performed for the param.</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.ParamSpecs">ParamSpecs
@@ -9917,6 +9930,19 @@ default is set, a Task may be executed without a supplied value for the
 parameter.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>enum</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
+If Enum is not set, no input validation is performed for the param.</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1beta1.ParamSpecs">ParamSpecs

pkg/apis/config/feature_flags.go

@@ -100,6 +100,10 @@ const (
 	EnableStepActions = "enable-step-actions"
 	// DefaultEnableStepActions is the default value for EnableStepActions
 	DefaultEnableStepActions = false
+	// EnableParamEnum is the flag to enabled enum in params
+	EnableParamEnum = "enable-param-enum"
+	// DefaultEnableParamEnum is the default value for EnableParamEnum
+	DefaultEnableParamEnum = false
 
 	disableAffinityAssistantKey         = "disable-affinity-assistant"
 	disableCredsInitKey                 = "disable-creds-init"
@@ -150,6 +154,7 @@ type FeatureFlags struct {
 	Coschedule                string
 	EnableCELInWhenExpression bool
 	EnableStepActions         bool
+	EnableParamEnum           bool
 }
 
 // GetFeatureFlagsConfigName returns the name of the configmap containing all
@@ -228,6 +233,9 @@ func NewFeatureFlagsFromMap(cfgMap map[string]string) (*FeatureFlags, error) {
 	if err := setFeature(EnableStepActions, DefaultEnableStepActions, &tc.EnableStepActions); err != nil {
 		return nil, err
 	}
+	if err := setFeature(EnableParamEnum, DefaultEnableParamEnum, &tc.EnableParamEnum); 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

@@ -75,6 +75,7 @@ func TestNewFeatureFlagsFromConfigMap(t *testing.T) {
 				Coschedule:                       config.CoscheduleDisabled,
 				EnableCELInWhenExpression:        true,
 				EnableStepActions:                true,
+				EnableParamEnum:                  true,
 			},
 			fileName: "feature-flags-all-flags-set",
 		},
@@ -277,6 +278,9 @@ func TestNewFeatureFlagsConfigMapErrors(t *testing.T) {
 	}, {
 		fileName: "feature-flags-invalid-enable-step-actions",
 		want:     `failed parsing feature flags config "invalid": strconv.ParseBool: parsing "invalid": invalid syntax`,
+	}, {
+		fileName: "feature-flags-invalid-enable-param-enum",
+		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

@@ -34,3 +34,4 @@ data:
   keep-pod-on-cancel: "true"
   enable-cel-in-whenexpression: "true"
   enable-step-actions: "true"
+  enable-param-enum: "true"

pkg/apis/config/testdata/feature-flags-invalid-enable-param-enum.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-param-enum: "invalid"

pkg/apis/pipeline/v1/openapi_generated.go

@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/tektoncd/pipeline/pkg/apis/config"
 	"github.com/tektoncd/pipeline/pkg/substitution"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/util/sets"
@@ -53,6 +54,10 @@ type ParamSpec struct {
 	// parameter.
 	// +optional
 	Default *ParamValue `json:"default,omitempty"`
+	// Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
+	// If Enum is not set, no input validation is performed for the param.
+	// +optional
+	Enum []string `json:"enum,omitempty"`
 }
 
 // ParamSpecs is a list of ParamSpec
@@ -132,22 +137,47 @@ func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
 
 // 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()
-	seen := sets.String{}
-	dups := sets.String{}
+	for dup := range findDups(names) {
+		errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", dup))
+	}
+	return errs
+}
+
+// validateParamEnum validates feature flag, duplication and allowed types for Param Enum
+func (ps ParamSpecs) validateParamEnums(ctx context.Context) *apis.FieldError {
 	var errs *apis.FieldError
-	for _, n := range names {
-		if seen.Has(n) {
-			dups.Insert(n)
+	for _, p := range ps {
+		if len(p.Enum) == 0 {
+			continue
+		}
+		if !config.FromContextOrDefaults(ctx).FeatureFlags.EnableParamEnum {
+			errs = errs.Also(errs, apis.ErrGeneric(fmt.Sprintf("feature flag %s should be set to true to use Enum", config.EnableParamEnum), "").ViaFieldKey("params", p.Name))
+		}
+		if p.Type != ParamTypeString {
+			errs = errs.Also(apis.ErrGeneric("enum can only be set with string type param", "").ViaFieldKey("params", p.Name))
+		}
+		for dup := range findDups(p.Enum) {
+			errs = errs.Also(apis.ErrGeneric(fmt.Sprintf("parameter enum value %v appears more than once", dup), "").ViaFieldKey("params", p.Name))
 		}
-		seen.Insert(n)
-	}
-	for n := range dups {
-		errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", n))
 	}
 	return errs
 }
 
+// findDups returns the duplicate element in the given slice
+func findDups(vals []string) sets.String {
+	seen := sets.String{}
+	dups := sets.String{}
+	for _, val := range vals {
+		if seen.Has(val) {
+			dups.Insert(val)
+		}
+		seen.Insert(val)
+	}
+	return dups
+}
+
 // Param declares an ParamValues to use for the parameter called name.
 type Param struct {
 	Name  string     `json:"name"`

pkg/apis/pipeline/v1/param_types.go

@@ -508,10 +508,9 @@ func TestPipelineTask_ValidateCustomTask(t *testing.T) {
 
 func TestPipelineTask_ValidateRegularTask_Success(t *testing.T) {
 	tests := []struct {
-		name                 string
-		tasks                PipelineTask
-		enableAlphaAPIFields bool
-		enableBetaAPIFields  bool
+		name      string
+		tasks     PipelineTask
+		configMap map[string]string
 	}{{
 		name: "pipeline task - valid taskRef name",
 		tasks: PipelineTask{
@@ -524,37 +523,51 @@ func TestPipelineTask_ValidateRegularTask_Success(t *testing.T) {
 			Name:     "foo",
 			TaskSpec: &EmbeddedTask{TaskSpec: getTaskSpec()},
 		},
+	}, {
+		name: "pipeline task - valid taskSpec with param enum",
+		tasks: PipelineTask{
+			Name: "foo",
+			TaskSpec: &EmbeddedTask{
+				TaskSpec: TaskSpec{
+					Steps: []Step{
+						{
+							Name:  "foo",
+							Image: "bar",
+						},
+					},
+					Params: []ParamSpec{
+						{
+							Name: "param1",
+							Type: ParamTypeString,
+							Enum: []string{"v1", "v2"},
+						},
+					},
+				},
+			},
+		},
+		configMap: map[string]string{"enable-param-enum": "true"},
 	}, {
 		name: "pipeline task - use of resolver with the feature flag set",
 		tasks: PipelineTask{
 			TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar"}},
 		},
-		enableBetaAPIFields: true,
+		configMap: map[string]string{"enable-api-field": "beta"},
 	}, {
 		name: "pipeline task - use of resolver with the feature flag set to alpha",
 		tasks: PipelineTask{
 			TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar"}},
 		},
-		enableAlphaAPIFields: true,
+		configMap: map[string]string{"enable-api-field": "alpha"},
 	}, {
 		name: "pipeline task - use of resolver params with the feature flag set",
 		tasks: PipelineTask{
 			TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar", Params: Params{{}}}},
 		},
-		enableBetaAPIFields: true,
+		configMap: map[string]string{"enable-api-field": "beta"},
 	}}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			ctx := context.Background()
-			cfg := &config.Config{
-				FeatureFlags: &config.FeatureFlags{},
-			}
-			if tt.enableAlphaAPIFields {
-				cfg.FeatureFlags.EnableAPIFields = config.AlphaAPIFields
-			} else if tt.enableBetaAPIFields {
-				cfg.FeatureFlags.EnableAPIFields = config.BetaAPIFields
-			}
-			ctx = config.ToContext(ctx, cfg)
+			ctx := cfgtesting.SetFeatureFlags(context.Background(), t, tt.configMap)
 			err := tt.tasks.validateTask(ctx)
 			if err != nil {
 				t.Errorf("PipelineTask.validateTask() returned error for valid pipeline task: %v", err)

pkg/apis/pipeline/v1/pipeline_types_test.go

@@ -433,11 +433,12 @@ func validatePipelineTasksWorkspacesUsage(wss []PipelineWorkspaceDeclaration, pt
 
 // ValidatePipelineParameterVariables validates parameters with those specified by each pipeline task,
 // (1) it validates the type of parameter is either string or array (2) parameter default value matches
-// with the type of that param
+// with the type of that param (3) no duplicateion, feature flag and allowed param type when using param enum
 func ValidatePipelineParameterVariables(ctx context.Context, tasks []PipelineTask, params ParamSpecs) (errs *apis.FieldError) {
 	// validates all the types within a slice of ParamSpecs
 	errs = errs.Also(ValidateParameterTypes(ctx, params).ViaField("params"))
 	errs = errs.Also(params.validateNoDuplicateNames())
+	errs = errs.Also(params.validateParamEnums(ctx))
 	for i, task := range tasks {
 		errs = errs.Also(task.Params.validateDuplicateParameters().ViaField("params").ViaIndex(i))
 	}