Skip to content

Commit

Permalink
when expressions with array results
Browse files Browse the repository at this point in the history 
Adding an example showcasing the usage of array results in when expressions,
including indexing into array results and array results with star notation.
This usage includes both `input` and `values` components of when expressions.

Also, added doc with syntax of these components.

Signed-off-by: pritidesai <pdesai@us.ibm.com>
  • Loading branch information
@pritidesai
pritidesai committed Feb 2, 2023
1 parent e14bcb0 commit 7cf648a
Show file tree
Hide file tree
Showing 2 changed files with 114 additions and 3 deletions.
10 changes: 7 additions & 3 deletions docs/pipelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -590,9 +590,13 @@ tasks:
To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using the `when` field. The `when` field allows you to list a series of references to `when` expressions.

The components of `when` expressions are `input`, `operator` and `values`:
- `input` is the input for the `when` expression which can be static inputs or variables ([`Parameters`](#specifying-parameters) or [`Results`](#using-results)). If the `input` is not provided, it defaults to an empty string.
- `operator` represents an `input`'s relationship to a set of `values`. A valid `operator` must be provided, which can be either `in` or `notin`.
- `values` is an array of string values. The `values` array must be provided and be non-empty. It can contain static values or variables ([`Parameters`](#specifying-parameters), [`Results`](#using-results) or [a Workspaces's `bound` state](#specifying-workspaces)).

| Component | Description | Syntax |
|------------|------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `input` | Input for the `when` expression, defaults to an empty string if not provided. | * Static values e.g. `"ubuntu"`<br/> * Variables ([parameters](#specifying-parameters) or [results](#using-results)) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"` |
| `operator` | `operator` represents an `input`'s relationship to a set of `values`, a valid `operator` must be provided. | `in` or `notin` |
| `values` | An array of string values, the `values` array must be provided and has to be non-empty. | * An array param e.g. `["$(params.images[*])"]`<br/> * An array result of a task `["$(tasks.task1.results.array-results[*])"]`<br/> * `values` can contain static values e.g. `"ubuntu"`<br/> * `values` can contain variables ([parameters](#specifying-parameters) or [results](#using-results)) or [a Workspaces's `bound` state](#specifying-workspaces) e.g. `["$(params.image)"]` or `["$(tasks.task1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]` |


The [`Parameters`](#specifying-parameters) are read from the `Pipeline` and [`Results`](#using-results) are read directly from previous [`Tasks`](#adding-tasks-to-the-pipeline). Using [`Results`](#using-results) in a `when` expression in a guarded `Task` introduces a resource dependency on the previous `Task` that produced the `Result`.

Expand Down
107 changes: 107 additions & 0 deletions examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
generateName: pipelinerun-with-when-expressions-using-array-results-
spec:
pipelineSpec:
params:
- name: images
type: array
description: The list of images
tasks:
- name: task1
taskSpec:
results:
# a list of images in array-result-1
- name: array-results-1
type: array
description: The array results
steps:
- name: write-array
image: bash:latest
script: |
#!/usr/bin/env bash
image1="abc.dev/notsofamousimage/image"
image2="ubuntu"
image3="xyz.dev/awesomeness/awesomeness"
echo -n "[\"$image1\", \"$image2\", \"$image3\"]" | tee $(results.array-results-1.path)
- name: task2
when:
# indexing into array results in input
- input: "$(tasks.task1.results.array-results-1[1])"
operator: in
values: ["ubuntu"]
taskSpec:
steps:
- name: say-hi
image: bash:latest
script: |
echo "hi"
- name: task3
when:
# indexing into array results in values
- input: "ubuntu"
operator: in
values: ["$(tasks.task1.results.array-results-1[1])"]
# indexing into array results in input and values
- input: "$(tasks.task1.results.array-results-1[2])"
operator: in
values: ["$(tasks.task1.results.array-results-1[2])"]
taskSpec:
steps:
- name: say-hello
image: bash:latest
script: |
echo "hello"
- name: task4
when:
# indexing into array results in input and using start notation in values
- input: "$(tasks.task1.results.array-results-1[1])"
operator: in
values: ["$(tasks.task1.results.array-results-1[*])"]
taskSpec:
steps:
- name: say-hi
image: bash:latest
script: |
echo "hi"
- name: task5
when:
# indexing into array result in input along with array param
- input: "$(tasks.task1.results.array-results-1[1])"
operator: notin
values: ["$(params.images[*])"]
taskSpec:
steps:
- name: do-not-execute
image: bash:latest
script: |
exit 1
finally:
- name: validate-tasks
taskSpec:
steps:
- name: validate-tasks-section
image: bash:latest
script: |
if [[ $(context.task2.status) != "Succeeded" ]]; then
echo "task2 should have been succeeded but instead has status - $(context.task2.status)"
exit 1
fi
if [[ $(context.task3.status) != "Succeeded" ]]; then
echo "task3 should have been succeeded but instead has status - $(context.task3.status)"
exit 1
fi
if [[ $(context.task4.status) != "Succeeded" ]]; then
echo "task3 should have been succeeded but instead has status - $(context.task4.status)"
exit 1
fi
if [[ $(context.task5.status) != "None" ]]; then
echo "task3 should have been succeeded but instead has status - $(context.task5.status)"
exit 1
fi
params:
- name: images
value:
- ubuntu
- alpine

0 comments on commit 7cf648a

Please sign in to comment.