Matrix

• Overview
• Configuring a Matrix
  • Concurrency Control
  • Parameters
  • Context Variables
  • Results
    • Specifying Results in a Matrix
    • Results from fanned out PipelineTasks
• Fan Out
  • PipelineTasks with Tasks

Overview

Matrix is used to fan out Tasks in a Pipeline. This doc will explain the details of matrix support in Tekton.

Documentation for specifying Matrix in a Pipeline:

• Specifying Matrix in Tasks
• Specifying Matrix in Finally Tasks
• Specifying Matrix in Custom Tasks

🌱 Matrix is an alpha feature. The enable-api-fields feature flag must be set to "alpha" to specify Matrix in a PipelineTask.

⚠️ This feature is in a preview mode. It is still in a very early stage of development and is not yet fully functional.

Configuring a Matrix

A Matrix supports the following features:

• Concurrency Control
• Parameters
• Context Variables
• 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 config defaults. When a Matrix in PipelineTask would generate more than the maximum TaskRuns or Runs, the Pipeline validation would fail.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
data:
  default-service-account: "tekton"
  default-timeout-minutes: "20"
  default-max-matrix-combinations-count: "1024"
  ...

For more information, see installation customizations.

Parameters

The Matrix will take Parameters of type "array" only, which will be supplied to the PipelineTask by substituting Parameters of type "string" in the underlying Task. The names of the Parameters in the Matrix must match the names of the Parameters in the underlying Task that they will be substituting.

In the example below, the test Task takes browser and platform Parameters of type "string". A Pipeline used to fan out the Task using Matrix would have two Parameters of type "array", and it would execute nine TaskRuns:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: platform-browser-tests
spec:
  params:
    - name: platforms
      type: array
      default:
        - linux
        - mac
        - windows
    - name: browsers
      type: array
      default:
        - chrome
        - safari
        - firefox    
  tasks:
  - name: fetch-repository
    taskRef:
      name: git-clone
    ...
  - name: test
    matrix:
      - name: platform
        value: $(params.platforms)
      - name: browser
        value: $(params.browsers)
    taskRef:
      name: browser-test
  ...

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.

Context Variables

Similarly to the Parameters in the Params field, the Parameters in the Matrix field will accept context variables that will be substituted, including:

• PipelineRun name, namespace and uid
• Pipeline name
• PipelineTask retries

Results

Specifying Results in a Matrix

Consuming Results from previous TaskRuns or Runs in a Matrix, which would dynamically generate TaskRuns or Runs from the fanned out PipelineTask, is not yet supported. This dynamic fan out of PipelineTasks through consuming Results will be supported soon.

Results from fanned out PipelineTasks

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.

Fan Out

PipelineTasks with Tasks

When a PipelineTask has a Task and a Matrix, the Task will be executed in parallel TaskRuns with substitutions from combinations of Parameters.

In the example below, nine TaskRuns are created with combinations of platforms (“linux”, “mac”, “windows”) and browsers (“chrome”, “safari”, “firefox”).

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: platform-browsers
  annotations:
    description: |
            A task that does something cool with platforms and browsers
spec:
  params:
    - name: platform
    - name: browser
  steps:
    - name: echo
      image: alpine
      script: |
                echo "$(params.platform) and $(params.browser)"
---
# run platform-browsers task with:
#   platforms: linux, mac, windows
#   browsers: chrome, safari, firefox
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: matrixed-pr-
spec:
  serviceAccountName: 'default'
  pipelineSpec:
    tasks:
      - name: platforms-and-browsers
        matrix:
          - name: platform
            value:
              - linux
              - mac
              - windows
          - name: browser
            value:
              - chrome
              - safari
              - firefox
        taskRef:
          name: platform-browsers

$ tkn taskruns list

NAME                                         STARTED        DURATION     STATUS
matrixed-pr-6lvzk-platforms-and-browsers-8   11 seconds ago   7 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-6   12 seconds ago   7 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-7   12 seconds ago   9 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-4   12 seconds ago   7 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-5   12 seconds ago   6 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-3   13 seconds ago   7 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-1   13 seconds ago   8 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-2   13 seconds ago   8 seconds    Succeeded
matrixed-pr-6lvzk-platforms-and-browsers-0   13 seconds ago   8 seconds    Succeeded