Skip to content

Commit

Permalink
Improve documentation about guarding Task execution using Conditions
Browse files Browse the repository at this point in the history
As noted in tektoncd#2635, it is not very clear what a Condition is in the context of a Pipeline.
And it is not clear how they work or what happens after.

This commit use the concept with "Guards" to explain how to guard Task execution within a Pipeline
using Condition resources. An example showing the flow when a Condition is not successfully evaluated
is also added.

/kind documentation
  • Loading branch information
jlpettersson committed May 17, 2020
1 parent 1fbac2a commit 29a0671
Showing 1 changed file with 30 additions and 18 deletions.
48 changes: 30 additions & 18 deletions docs/pipelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ weight: 3
- [Using the `from` parameter](#using-the-from-parameter)
- [Using the `runAfter` parameter](#using-the-runafter-parameter)
- [Using the `retries` parameter](#using-the-retries-parameter)
- [Specifying execution `Conditions`](#specifying-execution-conditions)
- [Guard `Task` execution using `Conditions`](#guard-task-execution-using-conditions)
- [Configuring the failure timeout](#configuring-the-failure-timeout)
- [Configuring execution results at the `Task` level](#configuring-execution-results-at-the-task-level)
- [Configuring execution results at the `Pipeline` level](#configuring-execution-results-at-the-pipeline-level)
Expand Down Expand Up @@ -312,32 +312,44 @@ tasks:
name: build-push
```

### Specifying execution `Conditions`
### Guard `Task` execution using `Conditions`

Sometimes you will need to run tasks only when some conditions are true. The `conditions` field
allows you to list a series of references to [`Conditions`](./conditions.md) that are run before the task
is run. If all of the conditions evaluate to true, the task is run. If any of the conditions are false,
the Task is not run. Its status.ConditionSucceeded is set to False with the reason set to `ConditionCheckFailed`.
However, unlike regular task failures, condition failures do not automatically fail the entire pipeline
run -- other tasks that are not dependent on the task (via `from` or `runAfter`) are still run.
To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using
the `conditions` field. The `conditions` field allows you to list a series of references to
[`Condition`](./conditions.md) resources. The declared `Conditions` are run before the `Task` is run.
If all of the conditions successfully evaluate, the `Task` is run. If any of the conditions fails,
the `Task` is not run and the `TaskRun` status field `ConditionSucceeded` is set to `False` with the
reason set to `ConditionCheckFailed`.

In this example, `is-master-branch` refers to a [Condition](conditions.md) resource. The `deploy`
task will only be executed if the condition successfully evaluates.

```yaml
tasks:
- name: conditional-task
taskRef:
name: build-push
- name: deploy-if-branch-is-master
conditions:
- conditionRef: my-condition
- conditionRef: is-master-branch
params:
- name: my-param
- name: branch-name
value: my-value
resources:
- name: workspace
resource: source-repo
taskRef:
name: deploy
```

In this example, `my-condition` refers to a [Condition](conditions.md) custom resource. The `build-push`
task will only be executed if the condition evaluates to true.
Unlike regular task failures, condition failures do not automatically fail the entire `PipelineRun` --
other tasks that are **not dependent** on the `Task` (via `from` or `runAfter`) are still run.

In this example, `(task C)` has a `condition` set to _guard_ its execution. If the condition
is **not** successfully evaluated, task `(task D)` will not be run, but all other tasks in the pipeline
that not depend on `(task C)` will be executed and the `PipelineRun` will successfully complete.

```
(task B) — (task E)
/
(task A)
\
(guarded task C) — (task D)
```

Resources in conditions can also use the [`from`](#using-the-from-parameter) field to indicate that they
expect the output of a previous task as input. As with regular Pipeline Tasks, using `from`
Expand Down

0 comments on commit 29a0671

Please sign in to comment.