Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

when expressions with array results (doc and example) #6092

Merged
merged 1 commit into from
Feb 6, 2023
Merged

when expressions with array results (doc and example) #6092

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/pipelines.md
View file
Open in desktop
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
Open in desktop
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