Matrix Promotion to Beta

Matrix was introduced in Tekton Pipelines 0.38. We have introduced a lot of testing around matrix feature including unit/e2e/integration tests. Matrix unblocks variety of use cases for systems migrating from travis/jenkins. This is a very crucial feature for many end-users while allowing to maintain clean, concise, and flexible catalog of pipelines. Part of #5265 and #6110 Signed-off-by: Priti Desai <pdesai@us.ibm.com>
tektoncd · Oct 18, 2023 · c7de7b1 · c7de7b1
1 parent 4ec4587
commit c7de7b1
Show file tree

Hide file tree

Showing 16 changed files with 135 additions and 165 deletions.
diff --git a/docs/additional-configs.md b/docs/additional-configs.md
@@ -311,7 +311,6 @@ Features currently in "alpha" are:
 | [Windows Scripts](./tasks.md#windows-scripts)                                                       | [TEP-0057](https://github.com/tektoncd/community/blob/main/teps/0057-windows-support.md)                                   | [v0.28.0](https://github.com/tektoncd/pipeline/releases/tag/v0.28.0) |                               |
 | [Debug](./debug.md)                                                                                 | [TEP-0042](https://github.com/tektoncd/community/blob/main/teps/0042-taskrun-breakpoint-on-failure.md)                     | [v0.26.0](https://github.com/tektoncd/pipeline/releases/tag/v0.26.0) |                               |
 | [Step and Sidecar Overrides](./taskruns.md#overriding-task-steps-and-sidecars)                      | [TEP-0094](https://github.com/tektoncd/community/blob/main/teps/0094-specifying-resource-requirements-at-runtime.md)       | [v0.34.0](https://github.com/tektoncd/pipeline/releases/tag/v0.34.0) |                               |
-| [Matrix](./matrix.md)                                                                               | [TEP-0090](https://github.com/tektoncd/community/blob/main/teps/0090-matrix.md)                                            | [v0.38.0](https://github.com/tektoncd/pipeline/releases/tag/v0.38.0) |                               |
 | [Task-level Resource Requirements](compute-resources.md#task-level-compute-resources-configuration) | [TEP-0104](https://github.com/tektoncd/community/blob/main/teps/0104-tasklevel-resource-requirements.md)                   | [v0.39.0](https://github.com/tektoncd/pipeline/releases/tag/v0.39.0) |                               |
 | [Trusted Resources](./trusted-resources.md)                                                         | [TEP-0091](https://github.com/tektoncd/community/blob/main/teps/0091-trusted-resources.md)                                 | N/A                                                                  | `trusted-resources-verification-no-match-policy`  |
 | [Larger Results via Sidecar Logs](#enabling-larger-results-using-sidecar-logs)                      | [TEP-0127](https://github.com/tektoncd/community/blob/main/teps/0127-larger-results-via-sidecar-logs.md)                   | [v0.43.0](https://github.com/tektoncd/pipeline/releases/tag/v0.43.0) | `results-from`                |
@@ -332,13 +331,14 @@ except where otherwise noted.
 
 Features currently in "beta" are:
 
-| Feature                                                            | Proposal                                                                                        | Alpha Release                                                        | Beta Release                                                         | Individual Flag | `enable-api-fields=beta` required for `v1beta1` |
-|:-------------------------------------------------------------------|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|:---------------------------------------------------------------------|:----------------|:---|
-| [Array Results and Array Indexing](pipelineruns.md#specifying-parameters)             | [TEP-0076](https://github.com/tektoncd/community/blob/main/teps/0076-array-result-types.md)     | [v0.38.0](https://github.com/tektoncd/pipeline/releases/tag/v0.38.0) | [v0.45.0](https://github.com/tektoncd/pipeline/releases/tag/v0.45.0) |                 | No |
-| [Object Parameters and Results](pipelineruns.md#specifying-parameters) | [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md) | | [v0.46.0](https://github.com/tektoncd/pipeline/releases/tag/v0.46.0) | | No |
-| [Remote Tasks](./taskruns.md#remote-tasks) and [Remote Pipelines](./pipelineruns.md#remote-pipelines) | [TEP-0060](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resolution.md) | | [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0) | | No |
-| [`Provenance` field in Status](pipeline-api.md#provenance)| [issue#5550](https://github.com/tektoncd/pipeline/issues/5550)| [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0)| [v0.48.0](https://github.com/tektoncd/pipeline/releases/tag/v0.48.0) | `enable-provenance-in-status`| No |
-| [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces)                     | [TEP-0029](https://github.com/tektoncd/community/blob/main/teps/0029-step-workspaces.md)                                   | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | [v0.50.0](https://github.com/tektoncd/pipeline/releases/tag/v0.50.0) | | Yes |
+| Feature                                                            | Proposal                                                                                        | Alpha Release                                                        | Beta Release                                                                                       | Individual Flag                                                      | `enable-api-fields=beta` required for `v1beta1` |
+|:-------------------------------------------------------------------|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|:------------------------------------------------|
+| [Array Results and Array Indexing](pipelineruns.md#specifying-parameters)             | [TEP-0076](https://github.com/tektoncd/community/blob/main/teps/0076-array-result-types.md)     | [v0.38.0](https://github.com/tektoncd/pipeline/releases/tag/v0.38.0) | [v0.45.0](https://github.com/tektoncd/pipeline/releases/tag/v0.45.0)                               |                                                                      | No                                              |
+| [Object Parameters and Results](pipelineruns.md#specifying-parameters) | [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md) | | [v0.46.0](https://github.com/tektoncd/pipeline/releases/tag/v0.46.0)                               |                                                                      | No                                              |
+| [Remote Tasks](./taskruns.md#remote-tasks) and [Remote Pipelines](./pipelineruns.md#remote-pipelines) | [TEP-0060](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resolution.md) | | [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0)                               |                                                                      | No                                              |
+| [`Provenance` field in Status](pipeline-api.md#provenance)| [issue#5550](https://github.com/tektoncd/pipeline/issues/5550)| [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0)| [v0.48.0](https://github.com/tektoncd/pipeline/releases/tag/v0.48.0)                               | `enable-provenance-in-status`                                        | No                                              |
+| [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces)                     | [TEP-0029](https://github.com/tektoncd/community/blob/main/teps/0029-step-workspaces.md)                                   | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | [v0.50.0](https://github.com/tektoncd/pipeline/releases/tag/v0.50.0)                               |                                                                      | Yes                                             |
+| [Matrix](./matrix.md)                                                                               | [TEP-0090](https://github.com/tektoncd/community/blob/main/teps/0090-matrix.md)                                            | [v0.38.0](https://github.com/tektoncd/pipeline/releases/tag/v0.38.0) |  [v0.53.0](https://github.com/tektoncd/pipeline/releases/tag/v0.53.0)                              |                                                 | No                                              |
 
 ## Enabling larger results using sidecar logs
 

diff --git a/docs/matrix.md b/docs/matrix.md
@@ -41,8 +41,8 @@ Documentation for specifying `Matrix` in a `Pipeline`:
 - [Specifying `Matrix` in `Finally Tasks`](pipelines.md#specifying-matrix-in-finally-tasks)
 - [Specifying `Matrix` in `Custom Tasks`](pipelines.md#specifying-matrix)
 
-> :seedling: **`Matrix` is an [alpha](additional-configs.md#alpha-features) feature.**
-> The `enable-api-fields` feature flag must be set to `"alpha"` to specify `Matrix` in a `PipelineTask`.
+> :seedling: **`Matrix` is an [beta](additional-configs.md#beta-features) feature.**
+> The `enable-api-fields` feature flag can be set to `"beta"` to specify `Matrix` in a `PipelineTask`.
 
 ## Configuring a Matrix
 
@@ -926,9 +926,8 @@ status:
 ```
 
 [cel]: https://github.com/tektoncd/experimental/tree/1609827ea81d05c8d00f8933c5c9d6150cd36989/cel
-[pr-with-matrix]: ../examples/v1/pipelineruns/alpha/pipelinerun-with-matrix.yaml
-[pr-with-matrix-and-results]: ../examples/v1/pipelineruns/alpha/pipelinerun-with-matrix-and-results.yaml
-[pr-with-matrix-context-variables]: ../examples/v1/pipelineruns/alpha/pipelinerun-with-matrix-context-variables.yaml
-[pr-with-matrix-emitting-results]: ../examples/v1/pipelineruns/alpha/pipelinerun-with-matrix-emitting-results.yaml
-
+[pr-with-matrix]: ../examples/v1/pipelineruns/beta/pipelinerun-with-matrix.yaml
+[pr-with-matrix-and-results]: ../examples/v1/pipelineruns/beta/pipelinerun-with-matrix-and-results.yaml
+[pr-with-matrix-context-variables]: ../examples/v1/pipelineruns/beta/pipelinerun-with-matrix-context-variables.yaml
+[pr-with-matrix-emitting-results]: ../examples/v1/pipelineruns/beta/pipelinerun-with-matrix-emitting-results.yaml
 [retries]: pipelines.md#using-the-retries-field
diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -392,8 +392,8 @@ spec:
 
 ### Specifying `Matrix` in `PipelineTasks`
 
-> :seedling: **`Matrix` is an [alpha](additional-configs.md#alpha-features) feature.**
-> The `enable-api-fields` feature flag must be set to `"alpha"` to specify `Matrix` in a `PipelineTask`.
+> :seedling: **`Matrix` is an [beta](additional-configs.md#beta-features) feature.**
+> The `enable-api-fields` feature flag can be set to `"beta"` to specify `Matrix` in a `PipelineTask`.
 
 You can also provide [`Parameters`](tasks.md#specifying-parameters) through the `matrix` field:
 
@@ -1351,8 +1351,8 @@ spec:
 
 ### Specifying `matrix` in `finally` tasks
 
-> :seedling: **`Matrix` is an [alpha](additional-configs.md#alpha-features) feature.**
-> The `enable-api-fields` feature flag must be set to `"alpha"` to specify `Matrix` in a `PipelineTask`.
+> :seedling: **`Matrix` is an [beta](additional-configs.md#beta-features) feature.**
+> The `enable-api-fields` feature flag can be set to `"beta"` to specify `Matrix` in a `PipelineTask`.
 
 Similar to `tasks`, you can also provide [`Parameters`](tasks.md#specifying-parameters) through `matrix`
 in `finally` tasks:

diff --git a/.../pipelinerun-with-matrix-and-results.yaml → .../pipelinerun-with-matrix-and-results.yaml b/.../pipelinerun-with-matrix-and-results.yaml → .../pipelinerun-with-matrix-and-results.yaml
diff --git a/...linerun-with-matrix-array-references.yaml → ...linerun-with-matrix-array-references.yaml b/...linerun-with-matrix-array-references.yaml → ...linerun-with-matrix-array-references.yaml
diff --git a/...inerun-with-matrix-context-variables.yaml → ...inerun-with-matrix-context-variables.yaml b/...inerun-with-matrix-context-variables.yaml → ...inerun-with-matrix-context-variables.yaml
diff --git a/...linerun-with-matrix-emitting-results.yaml → ...linerun-with-matrix-emitting-results.yaml b/...linerun-with-matrix-emitting-results.yaml → ...linerun-with-matrix-emitting-results.yaml
diff --git a/...linerun-with-matrix-include-explicit.yaml → ...linerun-with-matrix-include-explicit.yaml b/...linerun-with-matrix-include-explicit.yaml → ...linerun-with-matrix-include-explicit.yaml
diff --git a/...lpha/pipelinerun-with-matrix-include.yaml → ...beta/pipelinerun-with-matrix-include.yaml b/...lpha/pipelinerun-with-matrix-include.yaml → ...beta/pipelinerun-with-matrix-include.yaml
diff --git a/...neruns/alpha/pipelinerun-with-matrix.yaml → ...ineruns/beta/pipelinerun-with-matrix.yaml b/...neruns/alpha/pipelinerun-with-matrix.yaml → ...ineruns/beta/pipelinerun-with-matrix.yaml
diff --git a/pkg/apis/pipeline/v1/pipeline_types_test.go b/pkg/apis/pipeline/v1/pipeline_types_test.go
@@ -1069,7 +1069,7 @@ func TestPipelineTask_ValidateMatrix(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			featureFlags, _ := config.NewFeatureFlagsFromMap(map[string]string{
-				"enable-api-fields": "alpha",
+				"enable-api-fields": "beta",
 			})
 			defaults := &config.Defaults{
 				DefaultMaxMatrixCombinationsCount: 4,

diff --git a/pkg/apis/pipeline/v1/pipeline_validation.go b/pkg/apis/pipeline/v1/pipeline_validation.go
@@ -239,9 +239,9 @@ func (pt PipelineTask) Validate(ctx context.Context) (errs *apis.FieldError) {
 
 func (pt *PipelineTask) validateMatrix(ctx context.Context) (errs *apis.FieldError) {
 	if pt.IsMatrixed() {
-		// This is an alpha feature and will fail validation if it's used in a pipeline spec
-		// when the enable-api-fields feature gate is anything but "alpha".
-		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.AlphaAPIFields))
+		// This is a beta feature and will fail validation if it's used in a pipeline spec
+		// when the enable-api-fields feature gate is set to "stable".
+		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.BetaAPIFields))
 		errs = errs.Also(pt.Matrix.validateCombinationsCount(ctx))
 		errs = errs.Also(pt.Matrix.validateUniqueParams())
 	}

diff --git a/pkg/apis/pipeline/v1/pipeline_validation_test.go b/pkg/apis/pipeline/v1/pipeline_validation_test.go
@@ -18,7 +18,6 @@ package v1
 
 import (
 	"context"
-	"fmt"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
@@ -3500,74 +3499,60 @@ func TestPipelineTasksExecutionStatus(t *testing.T) {
 }
 
 // TestMatrixIncompatibleAPIVersions exercises validation of matrix
-// that requires alpha feature gate version in order to work.
+// that requires alpha/beta feature gate version in order to work.
 func TestMatrixIncompatibleAPIVersions(t *testing.T) {
+	task := PipelineTask{
+		Name:    "a-task",
+		TaskRef: &TaskRef{Name: "a-task"},
+		Matrix: &Matrix{
+			Params: Params{{
+				Name: "a-param", Value: ParamValue{Type: ParamTypeArray, ArrayVal: []string{"foo", "bar"}},
+			}}},
+	}
 	tests := []struct {
-		name            string
-		requiredVersion string
-		spec            PipelineSpec
+		name    string
+		pt      PipelineTask
+		version string
+		wantErr *apis.FieldError
 	}{{
-		name:            "matrix requires alpha - check tasks",
-		requiredVersion: "alpha",
-		spec: PipelineSpec{
-			Tasks: PipelineTaskList{{
-				Name:    "a-task",
-				TaskRef: &TaskRef{Name: "a-task"},
-				Matrix: &Matrix{
-					Params: Params{{
-						Name: "a-param", Value: ParamValue{Type: ParamTypeArray, ArrayVal: []string{"foo", "bar"}},
-					}}},
-			}},
-		},
-	}, {
-		name:            "matrix requires alpha - check finally tasks",
-		requiredVersion: "alpha",
-		spec: PipelineSpec{
-			Tasks: PipelineTaskList{{
-				Name:    "a-task",
-				TaskRef: &TaskRef{Name: "a-task"},
-			}},
-			Finally: PipelineTaskList{{
-				Name:    "b-task",
-				TaskRef: &TaskRef{Name: "b-task"},
-				Matrix: &Matrix{
-					Params: Params{{
-						Name: "a-param", Value: ParamValue{Type: ParamTypeArray, ArrayVal: []string{"foo", "bar"}},
-					}}},
-			}},
-		},
+		name:    "matrix can work with alpha",
+		pt:      task,
+		version: config.AlphaAPIFields,
+	}, {
+		name:    "matrix requires beta",
+		pt:      task,
+		version: config.BetaAPIFields,
+	}, {
+		name:    "matrix not allowed with stable version",
+		pt:      task,
+		version: config.StableAPIFields,
+		wantErr: apis.ErrGeneric("matrix requires \"enable-api-fields\" feature gate to be \"alpha\" or \"beta\" but it is \"stable\""),
 	}}
-	versions := []string{"alpha", "stable"}
-	for _, tt := range tests {
-		for _, version := range versions {
-			testName := fmt.Sprintf("(using %s) %s", version, tt.name)
-			t.Run(testName, func(t *testing.T) {
-				ps := tt.spec
-				featureFlags, _ := config.NewFeatureFlagsFromMap(map[string]string{
-					"enable-api-fields": version,
-				})
-				defaults := &config.Defaults{
-					DefaultMaxMatrixCombinationsCount: 4,
-				}
-				cfg := &config.Config{
-					FeatureFlags: featureFlags,
-					Defaults:     defaults,
-				}
-
-				ctx := config.ToContext(context.Background(), cfg)
 
-				ps.SetDefaults(ctx)
-				err := ps.Validate(ctx)
-
-				if tt.requiredVersion != version && err == nil {
-					t.Fatalf("no error received even though version required is %q while feature gate is %q", tt.requiredVersion, version)
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			defaults := &config.Defaults{
+				DefaultMaxMatrixCombinationsCount: 4,
+			}
+			featureFlags, _ := config.NewFeatureFlagsFromMap(map[string]string{
+				"enable-api-fields": test.version,
+			})
+			cfg := &config.Config{
+				Defaults:     defaults,
+				FeatureFlags: featureFlags,
+			}
+			ctx := config.ToContext(context.Background(), cfg)
+			err := test.pt.validateMatrix(ctx)
+			if test.wantErr != nil {
+				if d := cmp.Diff(test.wantErr.Error(), err.Error()); d != "" {
+					t.Error(diff.PrintWantGot(d))
 				}
-
-				if tt.requiredVersion == version && err != nil {
-					t.Fatalf("error received despite required version and feature gate matching %q: %v", version, err)
+			} else {
+				if err != nil {
+					t.Fatalf("PipelineTask.validateMatrix() error = %v", err)
 				}
-			})
-		}
+			}
+		})
 	}
 }
 
@@ -4049,7 +4034,7 @@ func Test_validateMatrix(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			featureFlags, _ := config.NewFeatureFlagsFromMap(map[string]string{
-				"enable-api-fields": "alpha",
+				"enable-api-fields": "beta",
 			})
 			defaults := &config.Defaults{
 				DefaultMaxMatrixCombinationsCount: 4,

diff --git a/pkg/apis/pipeline/v1beta1/pipeline_validation.go b/pkg/apis/pipeline/v1beta1/pipeline_validation.go
@@ -191,9 +191,9 @@ func (pt PipelineTask) Validate(ctx context.Context) (errs *apis.FieldError) {
 
 func (pt *PipelineTask) validateMatrix(ctx context.Context) (errs *apis.FieldError) {
 	if pt.IsMatrixed() {
-		// This is an alpha feature and will fail validation if it's used in a pipeline spec
-		// when the enable-api-fields feature gate is anything but "alpha".
-		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.AlphaAPIFields))
+		// This is a beta feature and will fail validation if it's used in a pipeline spec
+		// when the enable-api-fields feature gate is set to "stable".
+		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.BetaAPIFields))
 		errs = errs.Also(pt.Matrix.validateCombinationsCount(ctx))
 		errs = errs.Also(pt.Matrix.validateUniqueParams())
 	}