TEP-0118 matrix: add matrix.params filed

tektoncd · Sep 9, 2022 · e1fd727 · e1fd727
1 parent a70b109
commit e1fd727
Show file tree

Hide file tree

Showing 37 changed files with 1,348 additions and 847 deletions.
diff --git a/docs/matrix.md b/docs/matrix.md
@@ -101,10 +101,11 @@ spec:
     ...
   - name: test
     matrix:
-      - name: platform
-        value: $(params.platforms)
-      - name: browser
-        value: $(params.browsers)
+      params:
+        - name: platform
+          value: $(params.platforms)
+        - name: browser
+          value: $(params.browsers)
     taskRef:
       name: browser-test
   ...
@@ -134,11 +135,12 @@ spec:
     ...
   - name: test
     matrix:
-      - name: browser
-        value:
-          - chrome
-          - safari
-          - firefox
+      params:
+        - name: browser
+          value:
+            - chrome
+            - safari
+            - firefox
     params:
       - name: platform
         value: linux
@@ -243,16 +245,17 @@ spec:
     tasks:
       - name: platforms-and-browsers
         matrix:
-          - name: platform
-            value:
-              - linux
-              - mac
-              - windows
-          - name: browser
-            value:
-              - chrome
-              - safari
-              - firefox
+          params:
+            - name: platform
+              value:
+                - linux
+                - mac
+                - windows
+            - name: browser
+              value:
+                - chrome
+                - safari
+                - firefox
         taskRef:
           name: platform-browsers
 ```
@@ -291,16 +294,17 @@ spec:
   pipelineSpec:
     tasks:
     - matrix:
-      - name: platform
-        value:
-        - linux
-        - mac
-        - windows
-      - name: browser
-        value:
-        - chrome
-        - safari
-        - firefox
+        params:
+          - name: platform
+            value:
+              - linux
+              - mac
+              - windows
+          - name: browser
+              value:
+                - chrome
+                - safari
+                - firefox
       name: platforms-and-browsers
       taskRef:
         kind: Task
@@ -311,16 +315,17 @@ status:
   pipelineSpec:
     tasks:
       - matrix:
-          - name: platform
-            value:
-              - linux
-              - mac
-              - windows
-          - name: browser
-            value:
-              - chrome
-              - safari
-              - firefox
+          params:
+            - name: platform
+              value:
+                - linux
+                - mac
+                - windows
+            - name: browser
+              value:
+                - chrome
+                - safari
+                - firefox
         name: platforms-and-browsers
         taskRef:
           kind: Task
@@ -392,18 +397,19 @@ spec:
     tasks:
       - name: platforms-and-browsers
         matrix:
-          - name: type
-            value:
-              - "type(1)"
-              - "type(1.0)"
-          - name: colors
-            value:
-              - "{'blue': '0x000080', 'red': '0xFF0000'}['blue']"
-              - "{'blue': '0x000080', 'red': '0xFF0000'}['red']"
-          - name: bool
-            value:
-              - "type(1) == int"
-              - "{'blue': '0x000080', 'red': '0xFF0000'}['red'] == '0xFF0000'"
+          params:
+            - name: type
+              value:
+                - "type(1)"
+                - "type(1.0)"
+            - name: colors
+              value:
+                - "{'blue': '0x000080', 'red': '0xFF0000'}['blue']"
+                - "{'blue': '0x000080', 'red': '0xFF0000'}['red']"
+            - name: bool
+              value:
+                - "type(1) == int"
+                - "{'blue': '0x000080', 'red': '0xFF0000'}['red'] == '0xFF0000'"
         taskRef:
           apiVersion: cel.tekton.dev/v1alpha1
           kind: CEL
@@ -441,18 +447,19 @@ spec:
   pipelineSpec:
     tasks:
       - matrix:
-          - name: type
-            value:
-              - type(1)
-              - type(1.0)
-          - name: colors
-            value:
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''blue'']'
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red'']'
-          - name: bool
-            value:
-              - type(1) == int
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red''] == ''0xFF0000'''
+          params:
+            - name: type
+              value:
+                - type(1)
+                - type(1.0)
+            - name: colors
+              value:
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''blue'']'
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red'']'
+            - name: bool
+              value:
+                - type(1) == int
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red''] == ''0xFF0000'''
         name: platforms-and-browsers
         taskRef:
           apiVersion: cel.tekton.dev/v1alpha1
@@ -463,18 +470,19 @@ status:
   pipelineSpec:
     tasks:
       - matrix:
-          - name: type
-            value:
-              - type(1)
-              - type(1.0)
-          - name: colors
-            value:
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''blue'']'
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red'']'
-          - name: bool
-            value:
-              - type(1) == int
-              - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red''] == ''0xFF0000'''
+          params:
+            - name: type
+              value:
+                - type(1)
+                - type(1.0)
+            - name: colors
+              value:
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''blue'']'
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red'']'
+            - name: bool
+              value:
+                - type(1) == int
+                - '{''blue'': ''0x000080'', ''red'': ''0xFF0000''}[''red''] == ''0xFF0000'''
         name: platforms-and-browsers
         taskRef:
           apiVersion: cel.tekton.dev/v1alpha1
@@ -541,11 +549,12 @@ spec:
     tasks:
       - name: matrix-and-params
         matrix:
-          - name: platform
-            value:
-              - linux
-              - mac
-              - windows
+          params:
+            - name: platform
+              value:
+                - linux
+                - mac
+                - windows
         params:
           - name: browser
             value: chrome

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1171,6 +1171,40 @@ TaskSpec
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1.Matrix">Matrix
+</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>)
+</p>
+<div>
+<p>Matrix is used to fan out Tasks in a Pipeline</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>params</code><br/>
+<em>
+<a href="#tekton.dev/v1.Param">
+[]Param
+</a>
+</em>
+</td>
+<td>
+<p>Params is a list of parameters used to fan out the pipelineTask
+Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
+Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
+The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="tekton.dev/v1.OnErrorType">OnErrorType
 (<code>string</code> alias)</h3>
 <p>
@@ -1197,7 +1231,7 @@ TaskSpec
 <h3 id="tekton.dev/v1.Param">Param
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1.TaskRunSpec">TaskRunSpec</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.Matrix">Matrix</a>, <a href="#tekton.dev/v1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1.TaskRunSpec">TaskRunSpec</a>)
 </p>
 <div>
 <p>Param declares an ParamValues to use for the parameter called name.</p>
@@ -2268,8 +2302,8 @@ this Task executes. (Used to force a specific ordering in graph execution.)</p>
 <td>
 <code>matrix</code><br/>
 <em>
-<a href="#tekton.dev/v1.Param">
-[]Param
+<a href="#tekton.dev/v1.Matrix">
+Matrix
 </a>
 </em>
 </td>
@@ -8126,6 +8160,40 @@ TaskSpec
 </tr>
 </tbody>
 </table>
+<h3 id="tekton.dev/v1beta1.Matrix">Matrix
+</h3>
+<p>
+(<em>Appears on:</em><a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>)
+</p>
+<div>
+<p>Matrix is used to fan out Tasks in a Pipeline</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>params</code><br/>
+<em>
+<a href="#tekton.dev/v1beta1.Param">
+[]Param
+</a>
+</em>
+</td>
+<td>
+<p>Params is a list of parameters used to fan out the pipelineTask
+Params takes only <code>Parameters</code> of type <code>&quot;array&quot;</code>
+Each array element is supplied to the <code>PipelineTask</code> by substituting <code>params</code> of type <code>&quot;string&quot;</code> in the underlying <code>Task</code>.
+The names of the <code>params</code> in the <code>Matrix</code> must match the names of the <code>params</code> in the underlying <code>Task</code> that they will be substituting.</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="tekton.dev/v1beta1.OnErrorType">OnErrorType
 (<code>string</code> alias)</h3>
 <p>
@@ -8137,7 +8205,7 @@ TaskSpec
 <h3 id="tekton.dev/v1beta1.Param">Param
 </h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1alpha1.RunSpec">RunSpec</a>, <a href="#tekton.dev/v1beta1.CustomRunSpec">CustomRunSpec</a>, <a href="#tekton.dev/v1beta1.Matrix">Matrix</a>, <a href="#tekton.dev/v1beta1.PipelineRunSpec">PipelineRunSpec</a>, <a href="#tekton.dev/v1beta1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1beta1.ResolverRef">ResolverRef</a>, <a href="#tekton.dev/v1beta1.TaskRunInputs">TaskRunInputs</a>, <a href="#tekton.dev/v1beta1.TaskRunSpec">TaskRunSpec</a>)
 </p>
 <div>
 <p>Param declares an ParamValues to use for the parameter called name.</p>
@@ -9483,8 +9551,8 @@ outputs.</p>
 <td>
 <code>matrix</code><br/>
 <em>
-<a href="#tekton.dev/v1beta1.Param">
-[]Param
+<a href="#tekton.dev/v1beta1.Matrix">
+Matrix
 </a>
 </em>
 </td>

diff --git a/examples/v1beta1/pipelineruns/alpha/pipelinerun-with-matrix-and-results.yaml b/examples/v1beta1/pipelineruns/alpha/pipelinerun-with-matrix-and-results.yaml
@@ -51,14 +51,15 @@ spec:
                 printf firefox | tee /tekton/results/three
       - name: platforms-and-browsers-dag
         matrix:
-          - name: platform
-            value:
-              - $(tasks.get-platforms.results.one)
-              - $(tasks.get-platforms.results.two)
-              - $(tasks.get-platforms.results.three)
-          - name: browser
-            value:
-              - $(tasks.get-browsers.results.one)
-              - $(tasks.get-browsers.results.two)
+          params:
+            - name: platform
+              value:
+                - $(tasks.get-platforms.results.one)
+                - $(tasks.get-platforms.results.two)
+                - $(tasks.get-platforms.results.three)
+            - name: browser
+              value:
+                - $(tasks.get-browsers.results.one)
+                - $(tasks.get-browsers.results.two)
         taskRef:
           name: platform-browsers