displayName in matrix

Implementing proposal TEP-0150. Adding a functionality where the existing displayName can be used to configure unique names for each instance using the params from each combination such that the matrix instances in the Tekton Dashboard are rendered to distinguishable names. Also, repurposing an existing name field as part of the matrix.include[].name. If specified, a fully resolved name field is available in the childReferences. Signed-off-by: Priti Desai <pdesai@us.ibm.com>
tektoncd · Feb 22, 2024 · c6a0bed · c6a0bed
1 parent fd17c74
commit c6a0bed
Show file tree

Hide file tree

Showing 15 changed files with 737 additions and 22 deletions.
diff --git a/docs/matrix.md b/docs/matrix.md
@@ -155,6 +155,84 @@ Combinations generated
 { "IMAGE": "image-3", "DOCKERFILE": "path/to/Dockerfile3}
 ```
 
+## DisplayName
+
+Matrix creates multiple `taskRuns` with the same `pipelineTask`. Each `taskRun` has its unique combination `params` based
+on the `matrix` specifications. These `params` can now be surfaced and used to configure unique name of each `matrix`
+instance such that it is easier to distinguish all the instances based on their inputs.
+
+```yaml
+pipelineSpec:
+  tasks:
+    - name: platforms-and-browsers
+      displayName: "Platforms and Browsers: $(params.platform) and $(params.browser)"
+      matrix:
+        params:
+          - name: platform
+            value:
+              - linux
+              - mac
+              - windows
+          - name: browser
+            value:
+              - chrome
+              - safari
+              - firefox
+      taskRef:
+        name: platform-browsers
+```
+
+The `displayName` is available as part of `pipelineRun.status.childReferences` with each `taskRun`.
+This allows the clients to consume `displayName` wherever needed:
+
+```json
+[
+  {
+    "apiVersion": "tekton.dev/v1",
+    "displayName": "Platforms and Browsers: linux and chrome",
+    "kind": "TaskRun",
+    "name": "matrixed-pr-vcx79-platforms-and-browsers-0",
+    "pipelineTaskName": "platforms-and-browsers"
+  },
+  {
+    "apiVersion": "tekton.dev/v1",
+    "displayName": "Platforms and Browsers: mac and safari",
+    "kind": "TaskRun",
+    "name": "matrixed-pr-vcx79-platforms-and-browsers-1",
+    "pipelineTaskName": "platforms-and-browsers"
+  }
+]
+```
+
+### `matrix.include[].name`
+
+`matrix.include[]` section allows specifying a `name` along with a list of `params`. This `name` field is available as
+part of the `pipelineRun.status.childReferences[].displayName` if specified.
+
+`displayName` and `matrix.include[].name` can co-exist but `matrix.include[].name` takes higher precedence. It is also
+possible for the pipeline author to specify `params` in `matrix.include[].name` which are resolved in the `childReferences`.
+
+```yaml
+- name: platforms-and-browsers-with-include
+  matrix:
+    include:
+      - name: "Platform: $(params.platform)"
+        params:
+          - name: platform
+            value: linux111
+  params:
+    - name: browser
+      value: chrome
+```
+
+### Precedence Order
+
+| specification                                             | precedence                      | `childReferences[].displayName` |
+|-----------------------------------------------------------|---------------------------------|---------------------------------|
+| `tasks[].displayName`                                     | `tasks[].displayName`           | `tasks[].displayName`           |
+| `tasks[].matrix.include[].name`                           | `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` |
+| `tasks[].displayName` and `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` |
+
 ## Concurrency Control
 
 The default maximum count of `TaskRuns` or `Runs` from a given `Matrix` is **256**. To customize the maximum count of

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1333,6 +1333,18 @@ string
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>DisplayName is a user-facing name of the pipelineTask that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>pipelineTaskName</code><br/>
 <em>
 string
@@ -9513,6 +9525,18 @@ string
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>DisplayName is a user-facing name of the pipelineTask that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>pipelineTaskName</code><br/>
 <em>
 string

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -434,6 +434,10 @@ Specifying task results in the `displayName` does not introduce an inherent reso
 pipeline author is responsible for specifying dependency explicitly either using [runAfter](#using-the-runafter-field)
 or rely on [whenExpressions](#guard-task-execution-using-when-expressions) or [task results in params](#using-results).
 
+Fully resolved `displayName` is also available in the status as part of the `pipelineRun.status.childReferences`. The
+clients such as the dashboard, CLI, etc. can retrieve the `displayName` from the `childReferences`. The `displayName` mainly
+drives a better user experience and at the same time it is not validated for the content or length by the controller.
+
 ### Specifying Remote Tasks
 
 **([beta feature](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#beta-features))**
@@ -1542,6 +1546,10 @@ The `displayName` also allows you to parameterize the human-readable name of you
 [params](#specifying-parameters), [the task results](#consuming-task-execution-results-in-finally),
 and [the context variables](#context-variables).
 
+Fully resolved `displayName` is also available in the status as part of the `pipelineRun.status.childReferences`. The
+clients such as the dashboard, CLI, etc. can retrieve the `displayName` from the `childReferences`. The `displayName` mainly
+drives a better user experience and at the same time it is not validated for the content or length by the controller.
+
 ### Specifying `Workspaces` in `finally` tasks
 
 `finally` tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized

diff --git a/examples/v1/pipelineruns/beta/pipelinerun-with-matrix.yaml b/examples/v1/pipelineruns/beta/pipelinerun-with-matrix.yaml
@@ -25,6 +25,7 @@ spec:
   pipelineSpec:
     tasks:
       - name: platforms-and-browsers
+        displayName: "Platform: $(params.platform) with Browser: $(params.browser)"
         matrix:
           params:
             - name: platform
@@ -52,6 +53,18 @@ spec:
             value: chrome
         taskRef:
           name: platform-browsers
+      - name: matrix-and-params-include
+        matrix:
+          include:
+            - name: "Platform: $(params.platform) with Browser: $(params.browser)"
+              params:
+                - name: platform
+                  value: linux
+        params:
+          - name: browser
+            value: chrome
+        taskRef:
+          name: platform-browsers
       - name: matrix-params-with-empty-array-skipped
         matrix:
           params:

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/pipelinerun_types.go b/pkg/apis/pipeline/v1/pipelinerun_types.go
@@ -484,6 +484,9 @@ type ChildStatusReference struct {
 	runtime.TypeMeta `json:",inline"`
 	// Name is the name of the TaskRun or Run this is referencing.
 	Name string `json:"name,omitempty"`
+	// DisplayName is a user-facing name of the pipelineTask that may be
+	// used to populate a UI.
+	DisplayName string `json:"displayName,omitempty"`
 	// PipelineTaskName is the name of the PipelineTask this is referencing.
 	PipelineTaskName string `json:"pipelineTaskName,omitempty"`
 

diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -158,6 +158,10 @@
         "apiVersion": {
           "type": "string"
         },
+        "displayName": {
+          "description": "DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.",
+          "type": "string"
+        },
         "kind": {
           "type": "string"
         },

diff --git a/pkg/apis/pipeline/v1beta1/openapi_generated.go b/pkg/apis/pipeline/v1beta1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1beta1/pipelinerun_types.go b/pkg/apis/pipeline/v1beta1/pipelinerun_types.go
@@ -432,6 +432,9 @@ type ChildStatusReference struct {
 	runtime.TypeMeta `json:",inline"`
 	// Name is the name of the TaskRun or Run this is referencing.
 	Name string `json:"name,omitempty"`
+	// DisplayName is a user-facing name of the pipelineTask that may be
+	// used to populate a UI.
+	DisplayName string `json:"displayName,omitempty"`
 	// PipelineTaskName is the name of the PipelineTask this is referencing.
 	PipelineTaskName string `json:"pipelineTaskName,omitempty"`
 

diff --git a/pkg/apis/pipeline/v1beta1/swagger.json b/pkg/apis/pipeline/v1beta1/swagger.json
@@ -158,6 +158,10 @@
         "apiVersion": {
           "type": "string"
         },
+        "displayName": {
+          "description": "DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.",
+          "type": "string"
+        },
         "kind": {
           "type": "string"
         },

diff --git a/pkg/reconciler/pipelinerun/pipelinerun_test.go b/pkg/reconciler/pipelinerun/pipelinerun_test.go
@@ -10695,30 +10695,37 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-0
+    displayName: common-package go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-1
+    displayName: common-package go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-2
+    displayName: common-package s390x-no-race go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-3
+    displayName: common-package
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-4
+    displayName: common-package
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-5
+    displayName: common-package s390x-no-race
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-6
+    displayName: non-existent-arch
     pipelineTaskName: matrix-include
 `),
 	}, {
@@ -10888,30 +10895,37 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-0
+    displayName: common-package go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-1
+    displayName: common-package go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-2
+    displayName: common-package s390x-no-race go117-context
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-3
+    displayName: common-package
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-4
+    displayName: common-package
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-5
+    displayName: common-package s390x-no-race
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-6
+    displayName: non-existent-arch
     pipelineTaskName: matrix-include
 `),
 	}}
@@ -11129,14 +11143,17 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-0
+    displayName: build-1
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-1
+    displayName: build-2
     pipelineTaskName: matrix-include
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-include-2
+    displayName: build-3
     pipelineTaskName: matrix-include
 `),
 	},
@@ -14292,14 +14309,17 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-0
+    displayName: build-1
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-1
+    displayName: build-2
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-2
+    displayName: build-3
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
@@ -14456,14 +14476,17 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-0
+    displayName: build-1
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-1
+    displayName: build-2
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-2
+    displayName: build-3
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
@@ -14615,14 +14638,17 @@ status:
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-0
+    displayName: build-1
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-1
+    displayName: build-2
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun
     name: pr-matrix-emitting-results-2
+    displayName: build-3
     pipelineTaskName: matrix-emitting-results
   - apiVersion: tekton.dev/v1
     kind: TaskRun