Skip to content

Commit 40dcb05

Browse files
QuanZhang-WilliamQuanZhang-William
committed
[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
1 parent ae17f1c commit 40dcb05

23 files changed

+711
-227
lines changed

‎docs/pipeline-api.md

+26
Original file line numberDiff line numberDiff line change
@@ -1691,6 +1691,19 @@ default is set, a Task may be executed without a supplied value for the
16911691
parameter.</p>
16921692
</td>
16931693
</tr>
1694+
<tr>
1695+
<td>
1696+
<code>enum</code><br/>
1697+
<em>
1698+
[]string
1699+
</em>
1700+
</td>
1701+
<td>
1702+
<em>(Optional)</em>
1703+
<p>Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
1704+
If Enum is not set, no input validation is performed for the param.</p>
1705+
</td>
1706+
</tr>
16941707
</tbody>
16951708
</table>
16961709
<h3 id="tekton.dev/v1.ParamSpecs">ParamSpecs
@@ -9963,6 +9976,19 @@ default is set, a Task may be executed without a supplied value for the
99639976
parameter.</p>
99649977
</td>
99659978
</tr>
9979+
<tr>
9980+
<td>
9981+
<code>enum</code><br/>
9982+
<em>
9983+
[]string
9984+
</em>
9985+
</td>
9986+
<td>
9987+
<em>(Optional)</em>
9988+
<p>Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
9989+
If Enum is not set, no input validation is performed for the param.</p>
9990+
</td>
9991+
</tr>
99669992
</tbody>
99679993
</table>
99689994
<h3 id="tekton.dev/v1beta1.ParamSpecs">ParamSpecs

‎hack/ignored-openapi-violations.list

+2
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,5 @@ API rule violation: names_match,github.com/tektoncd/pipeline/pkg/apis/resolution
4141
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,RunSpec,Workspaces
4242
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Authorities
4343
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1,VerificationPolicySpec,Resources
44+
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1,ParamSpec,Enum
45+
API rule violation: list_type_missing,github.com/tektoncd/pipeline/pkg/apis/pipeline/v1,ParamSpec,Enum

‎pkg/apis/pipeline/v1/openapi_generated.go

+15
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pkg/apis/pipeline/v1/param_types.go

+39-9
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import (
2222
"fmt"
2323
"strings"
2424

25+
"github.com/tektoncd/pipeline/pkg/apis/config"
2526
"github.com/tektoncd/pipeline/pkg/substitution"
2627
corev1 "k8s.io/api/core/v1"
2728
"k8s.io/apimachinery/pkg/util/sets"
@@ -53,6 +54,10 @@ type ParamSpec struct {
5354
// parameter.
5455
// +optional
5556
Default *ParamValue `json:"default,omitempty"`
57+
// Enum declares a set of allowed param input values for tasks/pipelines that can be validated.
58+
// If Enum is not set, no input validation is performed for the param.
59+
// +optional
60+
Enum []string `json:"enum,omitempty"`
5661
}
5762

5863
// ParamSpecs is a list of ParamSpec
@@ -132,22 +137,47 @@ func (ps ParamSpecs) sortByType() (ParamSpecs, ParamSpecs, ParamSpecs) {
132137

133138
// validateNoDuplicateNames returns an error if any of the params have the same name
134139
func (ps ParamSpecs) validateNoDuplicateNames() *apis.FieldError {
140+
var errs *apis.FieldError
135141
names := ps.getNames()
136-
seen := sets.String{}
137-
dups := sets.String{}
142+
for dup := range findDups(names) {
143+
errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", dup))
144+
}
145+
return errs
146+
}
147+
148+
// validateParamEnum validates feature flag, duplication and allowed types for Param Enum
149+
func (ps ParamSpecs) validateParamEnums(ctx context.Context) *apis.FieldError {
138150
var errs *apis.FieldError
139-
for _, n := range names {
140-
if seen.Has(n) {
141-
dups.Insert(n)
151+
for _, p := range ps {
152+
if len(p.Enum) == 0 {
153+
continue
154+
}
155+
if !config.FromContextOrDefaults(ctx).FeatureFlags.EnableParamEnum {
156+
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))
157+
}
158+
if p.Type != ParamTypeString {
159+
errs = errs.Also(apis.ErrGeneric("enum can only be set with string type param", "").ViaFieldKey("params", p.Name))
160+
}
161+
for dup := range findDups(p.Enum) {
162+
errs = errs.Also(apis.ErrGeneric(fmt.Sprintf("parameter enum value %v appears more than once", dup), "").ViaFieldKey("params", p.Name))
142163
}
143-
seen.Insert(n)
144-
}
145-
for n := range dups {
146-
errs = errs.Also(apis.ErrGeneric("parameter appears more than once", "").ViaFieldKey("params", n))
147164
}
148165
return errs
149166
}
150167

168+
// findDups returns the duplicate element in the given slice
169+
func findDups(vals []string) sets.String {
170+
seen := sets.String{}
171+
dups := sets.String{}
172+
for _, val := range vals {
173+
if seen.Has(val) {
174+
dups.Insert(val)
175+
}
176+
seen.Insert(val)
177+
}
178+
return dups
179+
}
180+
151181
// Param declares an ParamValues to use for the parameter called name.
152182
type Param struct {
153183
Name string `json:"name"`

‎pkg/apis/pipeline/v1/pipeline_types_test.go

+30-17
Original file line numberDiff line numberDiff line change
@@ -508,10 +508,9 @@ func TestPipelineTask_ValidateCustomTask(t *testing.T) {
508508

509509
func TestPipelineTask_ValidateRegularTask_Success(t *testing.T) {
510510
tests := []struct {
511-
name string
512-
tasks PipelineTask
513-
enableAlphaAPIFields bool
514-
enableBetaAPIFields bool
511+
name string
512+
tasks PipelineTask
513+
configMap map[string]string
515514
}{{
516515
name: "pipeline task - valid taskRef name",
517516
tasks: PipelineTask{
@@ -524,37 +523,51 @@ func TestPipelineTask_ValidateRegularTask_Success(t *testing.T) {
524523
Name: "foo",
525524
TaskSpec: &EmbeddedTask{TaskSpec: getTaskSpec()},
526525
},
526+
}, {
527+
name: "pipeline task - valid taskSpec with param enum",
528+
tasks: PipelineTask{
529+
Name: "foo",
530+
TaskSpec: &EmbeddedTask{
531+
TaskSpec: TaskSpec{
532+
Steps: []Step{
533+
{
534+
Name: "foo",
535+
Image: "bar",
536+
},
537+
},
538+
Params: []ParamSpec{
539+
{
540+
Name: "param1",
541+
Type: ParamTypeString,
542+
Enum: []string{"v1", "v2"},
543+
},
544+
},
545+
},
546+
},
547+
},
548+
configMap: map[string]string{"enable-param-enum": "true"},
527549
}, {
528550
name: "pipeline task - use of resolver with the feature flag set",
529551
tasks: PipelineTask{
530552
TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar"}},
531553
},
532-
enableBetaAPIFields: true,
554+
configMap: map[string]string{"enable-api-field": "beta"},
533555
}, {
534556
name: "pipeline task - use of resolver with the feature flag set to alpha",
535557
tasks: PipelineTask{
536558
TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar"}},
537559
},
538-
enableAlphaAPIFields: true,
560+
configMap: map[string]string{"enable-api-field": "alpha"},
539561
}, {
540562
name: "pipeline task - use of resolver params with the feature flag set",
541563
tasks: PipelineTask{
542564
TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar", Params: Params{{}}}},
543565
},
544-
enableBetaAPIFields: true,
566+
configMap: map[string]string{"enable-api-field": "beta"},
545567
}}
546568
for _, tt := range tests {
547569
t.Run(tt.name, func(t *testing.T) {
548-
ctx := context.Background()
549-
cfg := &config.Config{
550-
FeatureFlags: &config.FeatureFlags{},
551-
}
552-
if tt.enableAlphaAPIFields {
553-
cfg.FeatureFlags.EnableAPIFields = config.AlphaAPIFields
554-
} else if tt.enableBetaAPIFields {
555-
cfg.FeatureFlags.EnableAPIFields = config.BetaAPIFields
556-
}
557-
ctx = config.ToContext(ctx, cfg)
570+
ctx := cfgtesting.SetFeatureFlags(context.Background(), t, tt.configMap)
558571
err := tt.tasks.validateTask(ctx)
559572
if err != nil {
560573
t.Errorf("PipelineTask.validateTask() returned error for valid pipeline task: %v", err)

‎pkg/apis/pipeline/v1/pipeline_validation.go

+2-1
Original file line numberDiff line numberDiff line change
@@ -433,11 +433,12 @@ func validatePipelineTasksWorkspacesUsage(wss []PipelineWorkspaceDeclaration, pt
433433

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

‎pkg/apis/pipeline/v1/pipeline_validation_test.go

+77-6
Original file line numberDiff line numberDiff line change
@@ -1295,13 +1295,14 @@ func TestFinallyTaskResultsToPipelineResults_Failure(t *testing.T) {
12951295

12961296
func TestValidatePipelineParameterVariables_Success(t *testing.T) {
12971297
tests := []struct {
1298-
name string
1299-
params []ParamSpec
1300-
tasks []PipelineTask
1298+
name string
1299+
params []ParamSpec
1300+
tasks []PipelineTask
1301+
configMap map[string]string
13011302
}{{
1302-
name: "valid string parameter variables",
1303+
name: "valid string parameter variables with enum",
13031304
params: []ParamSpec{{
1304-
Name: "baz", Type: ParamTypeString,
1305+
Name: "baz", Type: ParamTypeString, Enum: []string{"v1", "v2"},
13051306
}, {
13061307
Name: "foo-is-baz", Type: ParamTypeString,
13071308
}},
@@ -1312,6 +1313,7 @@ func TestValidatePipelineParameterVariables_Success(t *testing.T) {
13121313
Name: "a-param", Value: ParamValue{Type: ParamTypeString, StringVal: "$(params.baz) and $(params.foo-is-baz)"},
13131314
}},
13141315
}},
1316+
configMap: map[string]string{"enable-param-enum": "true"},
13151317
}, {
13161318
name: "valid string parameter variables in when expression",
13171319
params: []ParamSpec{{
@@ -1580,6 +1582,9 @@ func TestValidatePipelineParameterVariables_Success(t *testing.T) {
15801582
for _, tt := range tests {
15811583
t.Run(tt.name, func(t *testing.T) {
15821584
ctx := cfgtesting.EnableAlphaAPIFields(context.Background())
1585+
if tt.configMap != nil {
1586+
ctx = cfgtesting.SetFeatureFlags(ctx, t, tt.configMap)
1587+
}
15831588
err := ValidatePipelineParameterVariables(ctx, tt.tasks, tt.params)
15841589
if err != nil {
15851590
t.Errorf("Pipeline.ValidatePipelineParameterVariables() returned error for valid pipeline parameters: %v", err)
@@ -1921,7 +1926,7 @@ func TestValidatePipelineDeclaredParameterUsage_Failure(t *testing.T) {
19211926
t.Run(tt.name, func(t *testing.T) {
19221927
err := validatePipelineTaskParameterUsage(tt.tasks, tt.params)
19231928
if err == nil {
1924-
t.Errorf("Pipeline.ValidatePipelineParameterVariables() did not return error for invalid pipeline parameters")
1929+
t.Errorf("Pipeline.validatePipelineTaskParameterUsage() did not return error for invalid pipeline parameters")
19251930
}
19261931
if d := cmp.Diff(tt.expectedError.Error(), err.Error(), cmpopts.IgnoreUnexported(apis.FieldError{})); d != "" {
19271932
t.Errorf("PipelineSpec.Validate() errors diff %s", diff.PrintWantGot(d))
@@ -1936,7 +1941,69 @@ func TestValidatePipelineParameterVariables_Failure(t *testing.T) {
19361941
params []ParamSpec
19371942
tasks []PipelineTask
19381943
expectedError apis.FieldError
1944+
configMap map[string]string
19391945
}{{
1946+
name: "param enum with array type - failure",
1947+
params: []ParamSpec{{
1948+
Name: "param2",
1949+
Type: ParamTypeArray,
1950+
Enum: []string{"v1", "v2"},
1951+
}},
1952+
tasks: []PipelineTask{{
1953+
Name: "foo",
1954+
TaskRef: &TaskRef{Name: "foo-task"},
1955+
}},
1956+
configMap: map[string]string{
1957+
"enable-param-enum": "true",
1958+
},
1959+
expectedError: apis.FieldError{
1960+
Message: `enum can only be set with string type param`,
1961+
Paths: []string{"params[param2]"},
1962+
},
1963+
}, {
1964+
name: "param enum with object type - failure",
1965+
params: []ParamSpec{{
1966+
Name: "param2",
1967+
Type: ParamTypeObject,
1968+
Enum: []string{"v1", "v2"},
1969+
}},
1970+
tasks: []PipelineTask{{
1971+
Name: "foo",
1972+
TaskRef: &TaskRef{Name: "foo-task"},
1973+
}},
1974+
configMap: map[string]string{
1975+
"enable-param-enum": "true",
1976+
},
1977+
expectedError: apis.FieldError{
1978+
Message: `enum can only be set with string type param`,
1979+
Paths: []string{"params[param2]"},
1980+
},
1981+
}, {
1982+
name: "param enum with duplicate values - failure",
1983+
params: []ParamSpec{{
1984+
Name: "param1",
1985+
Type: ParamTypeString,
1986+
Enum: []string{"v1", "v1", "v2"},
1987+
}},
1988+
configMap: map[string]string{
1989+
"enable-param-enum": "true",
1990+
},
1991+
expectedError: apis.FieldError{
1992+
Message: `parameter enum value v1 appears more than once`,
1993+
Paths: []string{"params[param1]"},
1994+
},
1995+
}, {
1996+
name: "param enum with feature flag disabled - failure",
1997+
params: []ParamSpec{{
1998+
Name: "param1",
1999+
Type: ParamTypeString,
2000+
Enum: []string{"v1", "v2"},
2001+
}},
2002+
expectedError: apis.FieldError{
2003+
Message: `feature flag enable-param-enum should be set to true to use Enum`,
2004+
Paths: []string{"params[param1]"},
2005+
},
2006+
}, {
19402007
name: "invalid parameter type",
19412008
params: []ParamSpec{{
19422009
Name: "foo", Type: "invalidtype",
@@ -2105,6 +2172,10 @@ func TestValidatePipelineParameterVariables_Failure(t *testing.T) {
21052172
for _, tt := range tests {
21062173
t.Run(tt.name, func(t *testing.T) {
21072174
ctx := context.Background()
2175+
if tt.configMap != nil {
2176+
ctx = cfgtesting.SetFeatureFlags(ctx, t, tt.configMap)
2177+
}
2178+
21082179
err := ValidatePipelineParameterVariables(ctx, tt.tasks, tt.params)
21092180
if err == nil {
21102181
t.Errorf("Pipeline.ValidatePipelineParameterVariables() did not return error for invalid pipeline parameters")

‎pkg/apis/pipeline/v1/swagger.json

+8
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,14 @@
343343
"description": "Description is a user-facing description of the parameter that may be used to populate a UI.",
344344
"type": "string"
345345
},
346+
"enum": {
347+
"description": "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.",
348+
"type": "array",
349+
"items": {
350+
"type": "string",
351+
"default": ""
352+
}
353+
},
346354
"name": {
347355
"description": "Name declares the name by which a parameter is referenced.",
348356
"type": "string",

‎pkg/apis/pipeline/v1/task_validation.go

+1
Original file line numberDiff line numberDiff line change
@@ -435,6 +435,7 @@ func (p ParamSpec) ValidateObjectType(ctx context.Context) *apis.FieldError {
435435
func ValidateParameterVariables(ctx context.Context, steps []Step, params ParamSpecs) *apis.FieldError {
436436
var errs *apis.FieldError
437437
errs = errs.Also(params.validateNoDuplicateNames())
438+
errs = errs.Also(params.validateParamEnums(ctx))
438439
stringParams, arrayParams, objectParams := params.sortByType()
439440
stringParameterNames := sets.NewString(stringParams.getNames()...)
440441
arrayParameterNames := sets.NewString(arrayParams.getNames()...)

0 commit comments

Comments
 (0)