From 7cf648a8169e9a080bae403230a2499bef5171d3 Mon Sep 17 00:00:00 2001 From: pritidesai Date: Tue, 31 Jan 2023 11:49:00 -0800 Subject: [PATCH] when expressions with array results 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 --- docs/pipelines.md | 10 +- ...-when-expressions-using-array-results.yaml | 107 ++++++++++++++++++ 2 files changed, 114 insertions(+), 3 deletions(-) create mode 100644 examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml diff --git a/docs/pipelines.md b/docs/pipelines.md index 1cf7ba2d85f..78b161b493b 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -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"`
* 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[*])"]`
* An array result of a task `["$(tasks.task1.results.array-results[*])"]`
* `values` can contain static values e.g. `"ubuntu"`
* `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`. diff --git a/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml b/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml new file mode 100644 index 00000000000..775b0d94b52 --- /dev/null +++ b/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml @@ -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