PodTemplate param substitution on TaskRunSpecs to enable multi-arch builds with Matrix

docs/pipelineruns.md

@@ -24,6 +24,8 @@ weight: 204
     - [Mapping <code>ServiceAccount</code> credentials to <code>Tasks</code>](#mapping-serviceaccount-credentials-to-tasks)
     - [Specifying a <code>Pod</code> template](#specifying-a-pod-template)
     - [Specifying taskRunSpecs](#specifying-taskrunspecs)
+      - [Parameter Substitution in taskRunSpecs](#parameter-substitution-in-taskrunspecs)
+      - [Matrix Support with taskRunSpecs](#matrix-support-with-taskrunspecs)
     - [Specifying <code>Workspaces</code>](#specifying-workspaces)
       - [Propagated Workspaces](#propagated-workspaces)
         - [Referenced TaskRuns within Embedded PipelineRuns](#referenced-taskruns-within-embedded-pipelineruns)
@@ -1008,6 +1010,60 @@ spec:
 
 If a metadata key is present in different levels, the value that will be used in the `PipelineRun` is determined using this precedence order: `PipelineRun.spec.taskRunSpec.metadata` > `PipelineRun.metadata` > `Pipeline.spec.tasks.taskSpec.metadata`.
 
+#### Parameter Substitution in taskRunSpecs
+
+The `taskRunSpecs` supports parameter substitution in the `podTemplate` fields. This allows you to dynamically configure pod templates based on pipeline parameters, including those from Matrix tasks.
+
+For example, you can use parameter substitution to configure node selectors based on architecture parameters:
+
+```yaml
+spec:
+  taskRunSpecs:
+    - pipelineTaskName: build-task
+      podTemplate:
+        nodeSelector:
+          kubernetes.io/arch: $(params.arch)
+        tolerations:
+          - key: "environment"
+            operator: "Equal"
+            value: "$(params.env)"
+            effect: "NoSchedule"
+```
+
+#### Matrix Support with taskRunSpecs
+
+When using [`Matrix`](matrix.md) to fan out `PipelineTasks`, the `taskRunSpecs` can reference matrix parameters for dynamic pod template configuration. Each matrix combination will create a separate `TaskRun` with the appropriate parameter values substituted in the pod template.
+
+Here's an example showing how to use `taskRunSpecs` with matrix parameters:
+
+```yaml
+spec:
+  taskRunSpecs:
+    - pipelineTaskName: build-and-push-manifest
+      podTemplate:
+        nodeSelector:
+          kubernetes.io/arch: $(params.arch)
+  pipelineSpec:
+    tasks:
+      - name: build-and-push-manifest
+        matrix:
+          params:
+            - name: arch
+              value: ["amd64", "arm64"]
+        taskSpec:
+          params:
+            - name: arch
+          steps:
+            - name: build-and-push
+              image: ubuntu
+              script: |
+                echo "building on $(params.arch)"
+```
+
+In this example, the matrix will create two `TaskRuns` - one for `amd64` and one for `arm64`. Each will have its pod scheduled on the appropriate node architecture using the nodeSelector with the substituted parameter value.
+
+For a complete example, see [`pipelinerun-with-taskrunspecs-matrix-param-substitution.yaml`](../examples/v1/pipelineruns/pipelinerun-with-taskrunspecs-matrix-param-substitution.yaml).
+
 ### Specifying `Workspaces`
 
 If your `Pipeline` specifies one or more `Workspaces`, you must map those `Workspaces` to

docs/podtemplates.md

@@ -23,6 +23,29 @@ See the following for examples of specifying a Pod template:
 - [Specifying a Pod template for a `TaskRun`](./taskruns.md#specifying-a-pod-template)
 - [Specifying a Pod template for a `PipelineRun`](./pipelineruns.md#specifying-a-pod-template)
 
+## Parameter Substitution in Pod Templates
+
+When using Pod templates within `PipelineRun` [`taskRunSpecs`](./pipelineruns.md#specifying-taskrunspecs), you can use parameter substitution to dynamically configure Pod template fields based on pipeline parameters. This is particularly useful when working with [`Matrix`](./matrix.md) tasks that fan out with different parameter values.
+
+Parameter substitution uses the standard Tekton syntax `$(params.paramName)` and is supported in all Pod template fields that accept string values.
+
+Example with parameter substitution:
+```yaml
+taskRunSpecs:
+  - pipelineTaskName: build-task
+    podTemplate:
+      nodeSelector:
+        kubernetes.io/arch: $(params.arch)
+        environment: $(params.env)
+      tolerations:
+        - key: "workload-type"
+          operator: "Equal"
+          value: "$(params.workload)"
+          effect: "NoSchedule"
+```
+
+When used with Matrix tasks, each matrix combination will create a separate `TaskRun` with the parameter values substituted appropriately in the Pod template. For more information and examples, see [Matrix Support with taskRunSpecs](./pipelineruns.md#matrix-support-with-taskrunspecs).
+
 ## Supported fields
 
 Pod templates support fields listed in the table below.

docs/variables.md

@@ -176,3 +176,21 @@ For instructions on using variable substitutions see the relevant section of [th
 | `PipelineRun` | `spec.workspaces[].projected.sources[].configMap.items[].path`  |
 | `PipelineRun` | `spec.workspaces[].csi.driver`                                  |
 | `PipelineRun` | `spec.workspaces[].csi.nodePublishSecretRef.name`               |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.nodeSelector.*`                |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].key`             |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].operator`        |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].value`           |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].effect`          |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.affinity.*`                    |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.securityContext.*`             |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].name`                |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].configMap.name`      |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].secret.secretName`   |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.runtimeClassName`              |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.schedulerName`                 |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.priorityClassName`             |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.imagePullSecrets[].name`       |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.hostAliases[].ip`              |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.hostAliases[].hostnames[*]`    |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.topologySpreadConstraints[].topologyKey` |
+| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.topologySpreadConstraints[].whenUnsatisfiable` |

examples/v1/pipelineruns/beta/pipelinerun-with-matrix-and-taskrunspecs-param-substitution.yaml

@@ -0,0 +1,43 @@
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  generateName: matrix-podtemplate-taskrunspecs-test-
+spec:
+  taskRunSpecs:
+  - pipelineTaskName: build-and-push-manifest
+    podTemplate:
+      nodeSelector:
+        node-type: $(params.node-type)
+  - pipelineTaskName: create-manifest-list
+    podTemplate:
+      nodeSelector:
+        kubernetes.io/arch: amd64
+  pipelineSpec:
+    tasks:
+      - name: build-and-push-manifest
+        matrix:
+          params:
+          - name: node-type
+            value: ["worker-1", "worker-2"]
+        taskSpec:
+          results:
+            - name: manifest
+              type: string
+          params:
+            - name: node-type
+          steps:
+            - name: build-and-push
+              image: ubuntu
+              script: |
+                echo "building on $(params.node-type)"
+                echo "testmanifest-$(params.node-type)" | tee $(results.manifest.path)
+      - name: create-manifest-list
+        params:
+          - name: manifest
+            value: $(tasks.build-and-push-manifest.results.manifest[*])
+        taskSpec:
+          steps:
+            - name: echo-manifests
+              image: ubuntu
+              args: ["$(params.manifest[*])"]
+              script: echo "$@"

hack/setup-kind.sh

@@ -125,13 +125,17 @@ kind: Cluster
 nodes:
 - role: control-plane
   image: "${KIND_IMAGE}"
+  labels:
+    node-type: "control-plane"
 EOF
 
 for i in $(seq 1 1 "${NODE_COUNT}");
 do
   cat >> kind.yaml <<EOF
 - role: worker
   image: "${KIND_IMAGE}"
+  labels:
+    node-type: "worker-${i}"
 EOF
 done