Skip to content

Commit c22bec2

Browse files
dorzeldorzel
committed
Docs for podTemplate param substitution on TaskRuns/TaskRunSpecs
1 parent f44cec6 commit c22bec2

File tree

4 files changed

+140
-0
lines changed

4 files changed

+140
-0
lines changed

‎docs/pipelineruns.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ weight: 204
2424
- [Mapping <code>ServiceAccount</code> credentials to <code>Tasks</code>](#mapping-serviceaccount-credentials-to-tasks)
2525
- [Specifying a <code>Pod</code> template](#specifying-a-pod-template)
2626
- [Specifying taskRunSpecs](#specifying-taskrunspecs)
27+
- [Parameter Substitution in taskRunSpecs](#parameter-substitution-in-taskrunspecs)
28+
- [Matrix Support with taskRunSpecs](#matrix-support-with-taskrunspecs)
2729
- [Specifying <code>Workspaces</code>](#specifying-workspaces)
2830
- [Propagated Workspaces](#propagated-workspaces)
2931
- [Referenced TaskRuns within Embedded PipelineRuns](#referenced-taskruns-within-embedded-pipelineruns)
@@ -1008,6 +1010,60 @@ spec:
10081010

10091011
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`.
10101012

1013+
#### Parameter Substitution in taskRunSpecs
1014+
1015+
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.
1016+
1017+
For example, you can use parameter substitution to configure node selectors based on architecture parameters:
1018+
1019+
```yaml
1020+
spec:
1021+
taskRunSpecs:
1022+
- pipelineTaskName: build-task
1023+
podTemplate:
1024+
nodeSelector:
1025+
kubernetes.io/arch: $(params.arch)
1026+
tolerations:
1027+
- key: "environment"
1028+
operator: "Equal"
1029+
value: "$(params.env)"
1030+
effect: "NoSchedule"
1031+
```
1032+
1033+
#### Matrix Support with taskRunSpecs
1034+
1035+
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.
1036+
1037+
Here's an example showing how to use `taskRunSpecs` with matrix parameters:
1038+
1039+
```yaml
1040+
spec:
1041+
taskRunSpecs:
1042+
- pipelineTaskName: build-and-push-manifest
1043+
podTemplate:
1044+
nodeSelector:
1045+
kubernetes.io/arch: $(params.arch)
1046+
pipelineSpec:
1047+
tasks:
1048+
- name: build-and-push-manifest
1049+
matrix:
1050+
params:
1051+
- name: arch
1052+
value: ["amd64", "arm64"]
1053+
taskSpec:
1054+
params:
1055+
- name: arch
1056+
steps:
1057+
- name: build-and-push
1058+
image: ubuntu
1059+
script: |
1060+
echo "building on $(params.arch)"
1061+
```
1062+
1063+
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.
1064+
1065+
For a complete example, see [`pipelinerun-with-taskrunspecs-matrix-param-substitution.yaml`](../examples/v1/pipelineruns/pipelinerun-with-taskrunspecs-matrix-param-substitution.yaml).
1066+
10111067
### Specifying `Workspaces`
10121068

10131069
If your `Pipeline` specifies one or more `Workspaces`, you must map those `Workspaces` to

‎docs/podtemplates.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,29 @@ See the following for examples of specifying a Pod template:
2323
- [Specifying a Pod template for a `TaskRun`](./taskruns.md#specifying-a-pod-template)
2424
- [Specifying a Pod template for a `PipelineRun`](./pipelineruns.md#specifying-a-pod-template)
2525

26+
## Parameter Substitution in Pod Templates
27+
28+
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.
29+
30+
Parameter substitution uses the standard Tekton syntax `$(params.paramName)` and is supported in all Pod template fields that accept string values.
31+
32+
Example with parameter substitution:
33+
```yaml
34+
taskRunSpecs:
35+
- pipelineTaskName: build-task
36+
podTemplate:
37+
nodeSelector:
38+
kubernetes.io/arch: $(params.arch)
39+
environment: $(params.env)
40+
tolerations:
41+
- key: "workload-type"
42+
operator: "Equal"
43+
value: "$(params.workload)"
44+
effect: "NoSchedule"
45+
```
46+
47+
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).
48+
2649
## Supported fields
2750

2851
Pod templates support fields listed in the table below.

‎docs/variables.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,3 +176,21 @@ For instructions on using variable substitutions see the relevant section of [th
176176
| `PipelineRun` | `spec.workspaces[].projected.sources[].configMap.items[].path` |
177177
| `PipelineRun` | `spec.workspaces[].csi.driver` |
178178
| `PipelineRun` | `spec.workspaces[].csi.nodePublishSecretRef.name` |
179+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.nodeSelector.*` |
180+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].key` |
181+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].operator` |
182+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].value` |
183+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.tolerations[].effect` |
184+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.affinity.*` |
185+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.securityContext.*` |
186+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].name` |
187+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].configMap.name` |
188+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.volumes[].secret.secretName` |
189+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.runtimeClassName` |
190+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.schedulerName` |
191+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.priorityClassName` |
192+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.imagePullSecrets[].name` |
193+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.hostAliases[].ip` |
194+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.hostAliases[].hostnames[*]` |
195+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.topologySpreadConstraints[].topologyKey` |
196+
| `PipelineRun` | `spec.taskRunSpecs[].podTemplate.topologySpreadConstraints[].whenUnsatisfiable` |

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
apiVersion: tekton.dev/v1
2+
kind: PipelineRun
3+
metadata:
4+
generateName: matrix-podtemplate-taskrunspecs-test-
5+
spec:
6+
taskRunSpecs:
7+
- pipelineTaskName: build-and-push-manifest
8+
podTemplate:
9+
nodeSelector:
10+
kubernetes.io/arch: $(params.arch)
11+
- pipelineTaskName: create-manifest-list
12+
podTemplate:
13+
nodeSelector:
14+
kubernetes.io/arch: amd64
15+
pipelineSpec:
16+
tasks:
17+
- name: build-and-push-manifest
18+
matrix:
19+
params:
20+
- name: arch
21+
value: ["amd64", "arm64"]
22+
taskSpec:
23+
results:
24+
- name: manifest
25+
type: string
26+
params:
27+
- name: arch
28+
steps:
29+
- name: build-and-push
30+
image: ubuntu
31+
script: |
32+
echo "building on $(params.arch)"
33+
echo "testmanifest-$(params.arch)" | tee $(results.manifest.path)
34+
- name: create-manifest-list
35+
params:
36+
- name: manifest
37+
value: $(tasks.build-and-push-manifest.results.manifest[*])
38+
taskSpec:
39+
steps:
40+
- name: echo-manifests
41+
image: ubuntu
42+
args: ["$(params.manifest[*])"]
43+
script: echo "$@"

0 commit comments

Comments
 (0)