Skip to content

Commit 27ffd7d

Browse files
twoGiantstwoGiants
committed
docs: move step when expressions to task docs
Previously the docs for using when expressions to guard steps was under the StepActions docs. It was moved to the Tasks docs under "Tasks > Configuring a Task > Defining Steps > Guarding Step execution using when expressions". Issue #8623 Signed-off-by: Stanislav Jakuschevskij <[email protected]>
1 parent 47bcb09 commit 27ffd7d

File tree

2 files changed

+103
-103
lines changed

2 files changed

+103
-103
lines changed

‎docs/stepactions.md

-102
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ weight: 201
1818
- [Declaring VolumeMounts](#declaring-volumemounts)
1919
- [Referencing a StepAction](#referencing-a-stepaction)
2020
- [Specifying Remote StepActions](#specifying-remote-stepactions)
21-
- [Controlling Step Execution with when Expressions](#controlling-step-execution-with-when-expressions)
2221

2322
## Overview
2423
> :seedling: **`StepActions` is an [beta](additional-configs.md#beta-features) feature.**
@@ -536,104 +535,3 @@ spec:
536535
```
537536

538537
The default resolver type can be configured by the `default-resolver-type` field in the `config-defaults` ConfigMap (`alpha` feature). See [additional-configs.md](./additional-configs.md) for details.
539-
540-
### Controlling Step Execution with when Expressions
541-
542-
You can define `when` in a `step` to control its execution.
543-
544-
The components of `when` expressions are `input`, `operator`, `values`, `cel`:
545-
546-
| Component | Description | Syntax |
547-
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
548-
| `input` | Input for the `when` expression, defaults to an empty string if not provided. | * Static values e.g. `"ubuntu"`<br/> * Variables (parameters or results) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"` |
549-
| `operator` | `operator` represents an `input`'s relationship to a set of `values`, a valid `operator` must be provided. | `in` or `notin` |
550-
| `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/> * An array result of a step`["(steps.step1.results.array-results[*])"]`<br/>* `values` can contain static values e.g. `"ubuntu"`<br/> * `values` can contain variables (parameters or results) or a Workspaces's `bound` state e.g. `["$(params.image)"]` or `["$(steps.step1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]` or `["$(steps.step1.results.array-results[1])"]` |
551-
| `cel` | The Common Expression Language (CEL) implements common semantics for expression evaluation, enabling different applications to more easily interoperate. This is an `alpha` feature, `enable-cel-in-whenexpression` needs to be set to true to use this feature. | [cel-syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md#syntax)
552-
553-
The below example shows how to use when expressions to control step executions:
554-
555-
```yaml
556-
apiVersion: v1
557-
kind: PersistentVolumeClaim
558-
metadata:
559-
name: my-pvc-2
560-
spec:
561-
resources:
562-
requests:
563-
storage: 5Gi
564-
volumeMode: Filesystem
565-
accessModes:
566-
- ReadWriteOnce
567-
---
568-
apiVersion: tekton.dev/v1
569-
kind: TaskRun
570-
metadata:
571-
generateName: step-when-example
572-
spec:
573-
workspaces:
574-
- name: custom
575-
persistentVolumeClaim:
576-
claimName: my-pvc-2
577-
taskSpec:
578-
description: |
579-
A simple task that shows how to use when determine if a step should be executed
580-
steps:
581-
- name: should-execute
582-
image: bash:latest
583-
script: |
584-
#!/usr/bin/env bash
585-
echo "executed..."
586-
when:
587-
- input: "$(workspaces.custom.bound)"
588-
operator: in
589-
values: [ "true" ]
590-
- name: should-skip
591-
image: bash:latest
592-
script: |
593-
#!/usr/bin/env bash
594-
echo skipskipskip
595-
when:
596-
- input: "$(workspaces.custom2.bound)"
597-
operator: in
598-
values: [ "true" ]
599-
- name: should-continue
600-
image: bash:latest
601-
script: |
602-
#!/usr/bin/env bash
603-
echo blabalbaba
604-
- name: produce-step
605-
image: alpine
606-
results:
607-
- name: result2
608-
type: string
609-
script: |
610-
echo -n "foo" | tee $(step.results.result2.path)
611-
- name: run-based-on-step-results
612-
image: alpine
613-
script: |
614-
echo "wooooooo"
615-
when:
616-
- input: "$(steps.produce-step.results.result2)"
617-
operator: in
618-
values: [ "bar" ]
619-
workspaces:
620-
- name: custom
621-
```
622-
623-
The StepState for a skipped step looks like something similar to the below:
624-
```yaml
625-
{
626-
"container": "step-run-based-on-step-results",
627-
"imageID": "docker.io/library/alpine@sha256:c5b1261d6d3e43071626931fc004f70149baeba2c8ec672bd4f27761f8e1ad6b",
628-
"name": "run-based-on-step-results",
629-
"terminated": {
630-
"containerID": "containerd://bf81162e79cf66a2bbc03e3654942d3464db06ff368c0be263a8a70f363a899b",
631-
"exitCode": 0,
632-
"finishedAt": "2024-03-26T03:57:47Z",
633-
"reason": "Completed",
634-
"startedAt": "2024-03-26T03:57:47Z"
635-
},
636-
"terminationReason": "Skipped"
637-
}
638-
```
639-
Where `terminated.exitCode` is `0` and `terminationReason` is `Skipped` to indicate the Step exited successfully and was skipped.

‎docs/tasks.md

+103-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ weight: 201
1919
- [Accessing Step's `exitCode` in subsequent `Steps`](#accessing-steps-exitcode-in-subsequent-steps)
2020
- [Produce a task result with `onError`](#produce-a-task-result-with-onerror)
2121
- [Breakpoint on failure with `onError`](#breakpoint-on-failure-with-onerror)
22-
- [Redirecting step output streams with `stdoutConfig` and `stderrConfig`](#redirecting-step-output-streams-with-stdoutConfig-and-stderrConfig)
22+
- [Redirecting step output streams with `stdoutConfig` and `stderrConfig`](#redirecting-step-output-streams-with-stdoutconfig-and-stderrconfig)
23+
- [Guarding `Step` execution using `when` expressions](#guarding-step-execution-using-when-expressions)
2324
- [Specifying `Parameters`](#specifying-parameters)
2425
- [Specifying `Workspaces`](#specifying-workspaces)
2526
- [Emitting `Results`](#emitting-results)
@@ -553,6 +554,107 @@ spec:
553554
> - There is currently a limit on the overall size of the `Task` results. If the stdout/stderr of a step is set to the path of a `Task` result and the step prints too many data, the result manifest would become too large. Currently the entrypoint binary will fail if that happens.
554555
> - If the stdout/stderr of a `Step` is set to the path of a `Task` result, e.g. `$(results.empty.path)`, but that result is not defined for the `Task`, the `Step` will run but the output will be captured in a file named `$(results.empty.path)` in the current working directory. Similarly, any stubstition that is not valid, e.g. `$(some.invalid.path)/out.txt`, will be left as-is and will result in a file path `$(some.invalid.path)/out.txt` relative to the current working directory.
555556

557+
#### Guarding `Step` execution using `when` expressions
558+
559+
You can define `when` in a `step` to control its execution.
560+
561+
The components of `when` expressions are `input`, `operator`, `values`, `cel`:
562+
563+
| Component | Description | Syntax |
564+
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
565+
| `input` | Input for the `when` expression, defaults to an empty string if not provided. | * Static values e.g. `"ubuntu"`<br/> * Variables (parameters or results) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"` |
566+
| `operator` | `operator` represents an `input`'s relationship to a set of `values`, a valid `operator` must be provided. | `in` or `notin` |
567+
| `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/> * An array result of a step`["(steps.step1.results.array-results[*])"]`<br/>* `values` can contain static values e.g. `"ubuntu"`<br/> * `values` can contain variables (parameters or results) or a Workspaces's `bound` state e.g. `["$(params.image)"]` or `["$(steps.step1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]` or `["$(steps.step1.results.array-results[1])"]` |
568+
| `cel` | The Common Expression Language (CEL) implements common semantics for expression evaluation, enabling different applications to more easily interoperate. This is an `alpha` feature, `enable-cel-in-whenexpression` needs to be set to true to use this feature. | [cel-syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md#syntax)
569+
570+
The below example shows how to use when expressions to control step executions:
571+
572+
```yaml
573+
apiVersion: v1
574+
kind: PersistentVolumeClaim
575+
metadata:
576+
name: my-pvc-2
577+
spec:
578+
resources:
579+
requests:
580+
storage: 5Gi
581+
volumeMode: Filesystem
582+
accessModes:
583+
- ReadWriteOnce
584+
---
585+
apiVersion: tekton.dev/v1
586+
kind: TaskRun
587+
metadata:
588+
generateName: step-when-example
589+
spec:
590+
workspaces:
591+
- name: custom
592+
persistentVolumeClaim:
593+
claimName: my-pvc-2
594+
taskSpec:
595+
description: |
596+
A simple task that shows how to use when determine if a step should be executed
597+
steps:
598+
- name: should-execute
599+
image: bash:latest
600+
script: |
601+
#!/usr/bin/env bash
602+
echo "executed..."
603+
when:
604+
- input: "$(workspaces.custom.bound)"
605+
operator: in
606+
values: [ "true" ]
607+
- name: should-skip
608+
image: bash:latest
609+
script: |
610+
#!/usr/bin/env bash
611+
echo skipskipskip
612+
when:
613+
- input: "$(workspaces.custom2.bound)"
614+
operator: in
615+
values: [ "true" ]
616+
- name: should-continue
617+
image: bash:latest
618+
script: |
619+
#!/usr/bin/env bash
620+
echo blabalbaba
621+
- name: produce-step
622+
image: alpine
623+
results:
624+
- name: result2
625+
type: string
626+
script: |
627+
echo -n "foo" | tee $(step.results.result2.path)
628+
- name: run-based-on-step-results
629+
image: alpine
630+
script: |
631+
echo "wooooooo"
632+
when:
633+
- input: "$(steps.produce-step.results.result2)"
634+
operator: in
635+
values: [ "bar" ]
636+
workspaces:
637+
- name: custom
638+
```
639+
640+
The StepState for a skipped step looks like something similar to the below:
641+
```yaml
642+
{
643+
"container": "step-run-based-on-step-results",
644+
"imageID": "docker.io/library/alpine@sha256:c5b1261d6d3e43071626931fc004f70149baeba2c8ec672bd4f27761f8e1ad6b",
645+
"name": "run-based-on-step-results",
646+
"terminated": {
647+
"containerID": "containerd://bf81162e79cf66a2bbc03e3654942d3464db06ff368c0be263a8a70f363a899b",
648+
"exitCode": 0,
649+
"finishedAt": "2024-03-26T03:57:47Z",
650+
"reason": "Completed",
651+
"startedAt": "2024-03-26T03:57:47Z"
652+
},
653+
"terminationReason": "Skipped"
654+
}
655+
```
656+
Where `terminated.exitCode` is `0` and `terminationReason` is `Skipped` to indicate the Step exited successfully and was skipped.
657+
556658
### Specifying `Parameters`
557659

558660
You can specify parameters, such as compilation flags or artifact names, that you want to supply to the `Task` at execution time.

0 commit comments

Comments
 (0)