TEP-0118: Added Matrix.Include field in preview mode

This has been added to v1 and v1beta1. No functionality has been added at this time.
tektoncd · Feb 17, 2023 · c180c61 · c180c61
1 parent 7f837fe
commit c180c61
Show file tree

Hide file tree

Showing 9 changed files with 317 additions and 20 deletions.
diff --git a/docs/matrix.md b/docs/matrix.md
@@ -12,6 +12,7 @@ weight: 406
   - [Concurrency Control](#concurrency-control)
   - [Parameters](#parameters)
     - [Specifying both `params` and `matrix` in a `PipelineTask`](#specifying-both-params-and-matrix-in-a-pipelinetask)
+    - [Include](#Include)
   - [Context Variables](#context-variables)
   - [Results](#results)
     - [Specifying Results in a Matrix](#specifying-results-in-a-matrix)
@@ -24,7 +25,7 @@ weight: 406
 ## Overview
 
 `Matrix` is used to fan out `Tasks` in a `Pipeline`. This doc will explain the details of `matrix` support in
-Tekton. 
+Tekton.
 
 Documentation for specifying `Matrix` in a `Pipeline`:
 - [Specifying `Matrix` in `Tasks`](pipelines.md#specifying-matrix-in-pipelinetasks)
@@ -40,12 +41,12 @@ A `Matrix` supports the following features:
 * [Concurrency Control](#concurrency-control)
 * [Parameters](#parameters)
 * [Context Variables](#context-variables)
-* [Results](#results) 
+* [Results](#results)
 
 ### Concurrency Control
 
 The default maximum count of `TaskRuns` or `Runs` from a given `Matrix` is **256**. To customize the maximum count of
-`TaskRuns` or `Runs` generated from a given `Matrix`, configure the `default-max-matrix-combinations-count` in 
+`TaskRuns` or `Runs` generated from a given `Matrix`, configure the `default-max-matrix-combinations-count` in
 [config defaults](/config/config-defaults.yaml). When a `Matrix` in `PipelineTask` would generate more than the maximum
 `TaskRuns` or `Runs`, the `Pipeline` validation would fail.
 
@@ -92,7 +93,7 @@ spec:
       default:
         - chrome
         - safari
-        - firefox    
+        - firefox
   tasks:
   - name: fetch-repository
     taskRef:
@@ -110,7 +111,7 @@ spec:
   ...
 ```
 
-A `Parameter` can be passed to either the `matrix` or `params` field, not both. 
+A `Parameter` can be passed to either the `matrix` or `params` field, not both.
 
 For further details on specifying `Parameters` in the `Pipeline` and passing them to
 `PipelineTasks`, see [documentation](pipelines.md#specifying-parameters).
@@ -148,9 +149,14 @@ spec:
   ...
 ```
 
+### Include
+> :warning: This feature is in a preview mode.
+> It is still in a very early stage of development and is not yet fully functional.
+The `Include` section in the `Matrix` field exists, but is not yet functional.
+
 ### Context Variables
 
-Similarly to the `Parameters` in the `Params` field, the `Parameters` in the `Matrix` field will accept 
+Similarly to the `Parameters` in the `Params` field, the `Parameters` in the `Matrix` field will accept
 [context variables](variables.md) that will be substituted, including:
 
 * `PipelineRun` name, namespace and uid
@@ -161,7 +167,7 @@ Similarly to the `Parameters` in the `Params` field, the `Parameters` in the `Ma
 
 #### Specifying Results in a Matrix
 
-Consuming `Results` from previous `TaskRuns` or `Runs` in a `Matrix`, which would dynamically generate 
+Consuming `Results` from previous `TaskRuns` or `Runs` in a `Matrix`, which would dynamically generate
 `TaskRuns` or `Runs` from the fanned out `PipelineTask`, is supported. Producing `Results` in from a
 `PipelineTask` with a `Matrix` is not yet supported - see [further details](#results-from-fanned-out-pipelinetasks).
 
@@ -203,7 +209,7 @@ tasks:
 
 Consuming `Results` from fanned out `PipelineTasks` will not be in the supported in the initial iteration
 of `Matrix`. Supporting consuming `Results` from fanned out `PipelineTasks` will be revisited after array
-and object `Results` are supported. 
+and object `Results` are supported.
 
 ## Fan Out
 
@@ -487,15 +493,15 @@ status:
         name: platforms-and-browsers
         taskRef:
           apiVersion: cel.tekton.dev/v1alpha1
-          kind: CEL  
+          kind: CEL
   startTime: "2022-06-28T20:49:40Z"
   completionTime: "2022-06-28T20:49:41Z"
   conditions:
     - lastTransitionTime: "2022-06-28T20:49:41Z"
       message: 'Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0'
       reason: Succeeded
       status: "True"
-      type: Succeeded  
+      type: Succeeded
   childReferences:
     - apiVersion: tekton.dev/v1alpha1
       kind: Run
@@ -533,11 +539,11 @@ status:
 
 ## Retries
 
-The `retries` field is used to specify the number of times a `PipelineTask` should be retried when its `TaskRun` or 
-`Run` fails, see the [documentation][retries] for further details. When a `PipelineTask` is fanned out using `Matrix`, 
+The `retries` field is used to specify the number of times a `PipelineTask` should be retried when its `TaskRun` or
+`Run` fails, see the [documentation][retries] for further details. When a `PipelineTask` is fanned out using `Matrix`,
 a given `TaskRun` or `Run` executed will be retried as much as the field in the `retries` field of the `PipelineTask`.
 
-For example, the `PipelineTask` in this `PipelineRun` will be fanned out into three `TaskRuns` each of which will be 
+For example, the `PipelineTask` in this `PipelineRun` will be fanned out into three `TaskRuns` each of which will be
 retried once:
 
 ```yaml

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/pipeline_types.go b/pkg/apis/pipeline/v1/pipeline_types.go
@@ -212,6 +212,24 @@ type Matrix struct {
 	// The names of the `params` in the `Matrix` must match the names of the `params` in the underlying `Task` that they will be substituting.
 	// +listType=atomic
 	Params []Param `json:"params,omitempty"`
+
+	// Include is a list of MatrixInclude
+	// Note this field is in preview mode and not yet supported
+	// +optional
+	// +listType=atomic
+	Include []MatrixInclude `json:"include,omitempty"`
+}
+
+// MatrixInclude allows passing in a specific combinations of Parameters into the Matrix.
+// Note this struct is in preview mode and not yet supported
+type MatrixInclude struct {
+	// Name the specified combination
+	Name string `json:"name,omitempty"`
+
+	// Params takes only `Parameters` of type `"string"`
+	// The names of the `params` must match the names of the `params` in the underlying `Task`
+	// +listType=atomic
+	Params []Param `json:"params,omitempty"`
 }
 
 // validateRefOrSpec validates at least one of taskRef or taskSpec is specified
@@ -275,7 +293,7 @@ func (pt PipelineTask) validateTask(ctx context.Context) (errs *apis.FieldError)
 
 // IsMatrixed return whether pipeline task is matrixed
 func (pt *PipelineTask) IsMatrixed() bool {
-	return pt.Matrix != nil && len(pt.Matrix.Params) > 0
+	return pt.Matrix != nil && (len(pt.Matrix.Params) > 0 || len(pt.Matrix.Include) > 0)
 }
 
 func (pt *PipelineTask) validateMatrix(ctx context.Context) (errs *apis.FieldError) {

diff --git a/pkg/apis/pipeline/v1/pipeline_types_test.go b/pkg/apis/pipeline/v1/pipeline_types_test.go
@@ -532,15 +532,14 @@ func TestPipelineTaskList_Deps(t *testing.T) {
 				Values:   []string{"foo"},
 			}},
 			Matrix: &Matrix{
-				[]Param{{
+				Params: []Param{{
 					Value: ParamValue{
 						Type: ParamTypeArray,
 						ArrayVal: []string{
 							"$(tasks.task-2.results.result)",
 							"$(tasks.task-5.results.result)",
 						},
-					}},
-				},
+					}}},
 			},
 		}, {
 			Name: "task-7",
@@ -893,13 +892,52 @@ func TestPipelineTask_IsMatrixed(t *testing.T) {
 			expected: false,
 		},
 		{
-			name: "matrixed",
+			name: "matrixed with params",
 			arg: arg{
 				Matrix: &Matrix{
 					Params: []Param{{Name: "platform", Value: ParamValue{ArrayVal: []string{"linux", "windows"}}}},
 				},
 			},
 			expected: true,
+		}, {
+			name: "matrixed with include",
+			arg: arg{
+				Matrix: &Matrix{
+					Include: []MatrixInclude{
+						{Name: "build-1"},
+						{Params: []Param{
+							{Name: "IMAGE", Value: ParamValue{StringVal: "image-1"}},
+							{Name: "DOCKERFILE", Value: ParamValue{StringVal: "path/to/Dockerfile1"}},
+						}},
+						{Name: "build-2"},
+						{Params: []Param{
+							{Name: "IMAGE", Value: ParamValue{StringVal: "image-2"}},
+							{Name: "DOCKERFILE", Value: ParamValue{StringVal: "path/to/Dockerfile2"}},
+						}},
+						{Name: "build-3"},
+						{Params: []Param{
+							{Name: "IMAGE", Value: ParamValue{StringVal: "image-3"}},
+							{Name: "DOCKERFILE", Value: ParamValue{StringVal: "path/to/Dockerfile3"}},
+						}},
+					},
+				},
+			},
+			expected: true,
+		}, {
+			name: "matrixed with params and include",
+			arg: arg{
+				Matrix: &Matrix{
+					Params: []Param{{Name: "GOARCH", Value: ParamValue{ArrayVal: []string{"linux/amd64", "linux/ppc64le", "linux/s390x"}}}},
+					Include: []MatrixInclude{
+						{Name: "s390x-no-race"},
+						{Params: []Param{
+							{Name: "GOARCH", Value: ParamValue{StringVal: "linux/s390x"}},
+							{Name: "flags", Value: ParamValue{StringVal: "-cover -v"}},
+						}},
+					},
+				},
+			},
+			expected: true,
 		},
 	}
 	for _, tc := range testCases {

diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -289,6 +289,15 @@
       "description": "Matrix is used to fan out Tasks in a Pipeline",
       "type": "object",
       "properties": {
+        "include": {
+          "description": "Include is a list of MatrixInclude Note this field is in preview mode and not yet supported",
+          "type": "array",
+          "items": {
+            "default": {},
+            "$ref": "#/definitions/v1.MatrixInclude"
+          },
+          "x-kubernetes-list-type": "atomic"
+        },
         "params": {
           "description": "Params is a list of parameters used to fan out the pipelineTask Params takes only `Parameters` of type `\"array\"` Each array element is supplied to the `PipelineTask` by substituting `params` of type `\"string\"` in the underlying `Task`. The names of the `params` in the `Matrix` must match the names of the `params` in the underlying `Task` that they will be substituting.",
           "type": "array",
@@ -300,6 +309,25 @@
         }
       }
     },
+    "v1.MatrixInclude": {
+      "description": "MatrixInclude allows passing in a specific combinations of Parameters into the Matrix. Note this struct is in preview mode and not yet supported",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Name the specified combination",
+          "type": "string"
+        },
+        "params": {
+          "description": "Params takes only `Parameters` of type `\"string\"` The names of the `params` must match the names of the `params` in the underlying `Task`",
+          "type": "array",
+          "items": {
+            "default": {},
+            "$ref": "#/definitions/v1.Param"
+          },
+          "x-kubernetes-list-type": "atomic"
+        }
+      }
+    },
     "v1.Param": {
       "description": "Param declares an ParamValues to use for the parameter called name.",
       "type": "object",