diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md index f08d28402b4..d919cb51d42 100644 --- a/docs/pipelineruns.md +++ b/docs/pipelineruns.md @@ -414,7 +414,7 @@ If you set the timeout to 0, the `PipelineRun` fails immediately upon encounteri > :warning: ** `timeout`will be deprecated in future versions. Consider using `timeouts` instead. -You can use the `timeouts` field to set the `PipelineRun's` desired timeout value in minutes. There are three sub-fields than can be used to specify failures timeout for the entire pipeline, for tasks, and for finally tasks. +You can use the `timeouts` field to set the `PipelineRun's` desired timeout value in minutes. There are three sub-fields than can be used to specify failures timeout for the entire pipeline, for tasks, and for `finally` tasks. ```yaml timeouts: @@ -563,7 +563,7 @@ Task Runs: To cancel a `PipelineRun` that's currently executing, update its definition to mark it as "PipelineRunCancelled". When you do so, the spawned `TaskRuns` are also marked as cancelled, all associated `Pods` are deleted, and their `Retries` are not executed. -Pending final tasks are not scheduled. +Pending `finally` tasks are not scheduled. For example: @@ -587,7 +587,7 @@ is currently an **_alpha feature_**. To gracefully cancel a `PipelineRun` that's currently executing, update its definition to mark it as "CancelledRunFinally". When you do so, the spawned `TaskRuns` are also marked as cancelled, all associated `Pods` are deleted, and their `Retries` are not executed. -Final tasks are scheduled normally. +`finally` tasks are scheduled normally. For example: @@ -606,7 +606,7 @@ spec: To gracefully stop a `PipelineRun` that's currently executing, update its definition to mark it as "StoppedRunFinally". When you do so, the spawned `TaskRuns` are completed normally, -but no new non-final task is scheduled. Final tasks are executed afterwards. +but no new non-`finally` task is scheduled. `finally` tasks are executed afterwards. For example: ```yaml diff --git a/docs/pipelines.md b/docs/pipelines.md index 855cdd9aac2..1f4b994c10a 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -27,21 +27,21 @@ weight: 400 - [Configuring the `Task` execution order](#configuring-the-task-execution-order) - [Adding a description](#adding-a-description) - [Adding `Finally` to the `Pipeline`](#adding-finally-to-the-pipeline) - - [Specifying `Workspaces` in Final Tasks](#specifying-workspaces-in-final-tasks) - - [Specifying `Parameters` in Final Tasks](#specifying-parameters-in-final-tasks) + - [Specifying `Workspaces` in `finally` tasks](#specifying-workspaces-in-finally-tasks) + - [Specifying `Parameters` in `finally` tasks](#specifying-parameters-in-finally-tasks) - [Consuming `Task` execution results in `finally`](#consuming-task-execution-results-in-finally) - [`PipelineRun` Status with `finally`](#pipelinerun-status-with-finally) - [Using Execution `Status` of `pipelineTask`](#using-execution-status-of-pipelinetask) - [Using Aggregate Execution `Status` of All `Tasks`](#using-aggregate-execution-status-of-all-tasks) - - [Guard `Finally Task` execution using `when` expressions](#guard-finally-task-execution-using-when-expressions) - - [`when` expressions using `Parameters` in `Finally Tasks`](#when-expressions-using-parameters-in-finally-tasks) - - [`when` expressions using `Results` in `Finally Tasks`](#when-expressions-using-results-in-finally-tasks) - - [`when` expressions using `Execution Status` of `PipelineTask` in `Finally Tasks`](#when-expressions-using-execution-status-of-pipelinetask-in-finally-tasks) - - [`when` expressions using `Aggregate Execution Status` of `Tasks` in `Finally Tasks`](#when-expressions-using-aggregate-execution-status-of-tasks-in-finally-tasks) + - [Guard `finally` `task` execution using `when` expressions](#guard-finally-task-execution-using-when-expressions) + - [`when` expressions using `Parameters` in `finally` `tasks`](#when-expressions-using-parameters-in-finally-tasks) + - [`when` expressions using `Results` in `finally` `tasks`](#when-expressions-using-results-in-finally-tasks) + - [`when` expressions using `Execution Status` of `PipelineTask` in `finally` `tasks`](#when-expressions-using-execution-status-of-pipelinetask-in-finally-tasks) + - [`when` expressions using `Aggregate Execution Status` of `Tasks` in `finally` `tasks`](#when-expressions-using-aggregate-execution-status-of-tasks-in-finally-tasks) - [Known Limitations](#known-limitations) - - [Specifying `Resources` in Final Tasks](#specifying-resources-in-final-tasks) - - [Cannot configure the Final Task execution order](#cannot-configure-the-final-task-execution-order) - - [Cannot specify execution `Conditions` in Final Tasks](#cannot-specify-execution-conditions-in-final-tasks) + - [Specifying `Resources` in `finally` tasks](#specifying-resources-in-finally-tasks) + - [Cannot configure the `finally` task execution order](#cannot-configure-the-finally-task-execution-order) + - [Cannot specify execution `Conditions` in `finally` tasks](#cannot-specify-execution-conditions-in-finally-tasks) - [Cannot configure `Pipeline` result with `finally`](#cannot-configure-pipeline-result-with-finally) - [Using Custom Tasks](#using-custom-tasks) - [Specifying the target Custom Task](#specifying-the-target-custom-task) @@ -1015,9 +1015,9 @@ The `description` field is an optional field and can be used to provide descript ## Adding `Finally` to the `Pipeline` -You can specify a list of one or more final tasks under `finally` section. Final tasks are guaranteed to be executed -in parallel after all `PipelineTasks` under `tasks` have completed regardless of success or error. Final tasks are very -similar to `PipelineTasks` under `tasks` section and follow the same syntax. Each final task must have a +You can specify a list of one or more final tasks under `finally` section. `finally` tasks are guaranteed to be executed +in parallel after all `PipelineTasks` under `tasks` have completed regardless of success or error. `finally` tasks are very +similar to `PipelineTasks` under `tasks` section and follow the same syntax. Each `finally` task must have a [valid](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) `name` and a [taskRef or taskSpec](taskruns.md#specifying-the-target-task). For example: @@ -1033,11 +1033,11 @@ spec: name: cleanup ``` -### Specifying `Workspaces` in Final Tasks +### Specifying `Workspaces` in `finally` tasks -Finally tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized +`finally` tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized e.g. a mount point for credentials held in Secrets. To support that requirement, you can specify one or more -`Workspaces` in the `workspaces` field for the final tasks similar to `tasks`. +`Workspaces` in the `workspaces` field for the `finally` tasks similar to `tasks`. ```yaml spec: @@ -1066,9 +1066,9 @@ spec: workspace: shared-workspace ``` -### Specifying `Parameters` in Final Tasks +### Specifying `Parameters` in `finally` tasks -Similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters) in final tasks: +Similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters) in `finally` tasks: ```yaml spec: @@ -1087,7 +1087,7 @@ spec: ### Consuming `Task` execution results in `finally` -Final tasks can be configured to consume `Results` of `PipelineTask` from the `tasks` section: +`finally` tasks can be configured to consume `Results` of `PipelineTask` from the `tasks` section: ```yaml spec: @@ -1101,19 +1101,18 @@ spec: - name: commit value: $(tasks.clone-app-repo.results.commit) ``` -**Note:** The scheduling of such final task does not change, it will still be executed in parallel with other -final tasks after all non-final tasks are done. +**Note:** The scheduling of such `finally` task does not change, it will still be executed in parallel with other +`finally` tasks after all non-`finally` tasks are done. -The controller resolves task results before executing the finally task `discover-git-commit`. If the task +The controller resolves task results before executing the `finally` task `discover-git-commit`. If the task `clone-app-repo` failed or skipped with [when expression](#guard-task-execution-using-when-expressions) resulting in -uninitialized task result `commit`, the finally Task `discover-git-commit` will be included in the list of -`skippedTasks` and continues executing rest of the final tasks. The pipeline exits with `completion` instead of -`success` if a finally task is added to the list of `skippedTasks`. - +uninitialized task result `commit`, the `finally` Task `discover-git-commit` will be included in the list of +`skippedTasks` and continues executing rest of the `finally` tasks. The pipeline exits with `completion` instead of +`success` if a `finally` task is added to the list of `skippedTasks`. ### `PipelineRun` Status with `finally` -With `finally`, `PipelineRun` status is calculated based on `PipelineTasks` under `tasks` section and final tasks. +With `finally`, `PipelineRun` status is calculated based on `PipelineTasks` under `tasks` section and `finally` tasks. Without `finally`: @@ -1125,20 +1124,20 @@ Without `finally`: With `finally`: -| `PipelineTasks` under `tasks` | Final Tasks | `PipelineRun` status | Reason | +| `PipelineTasks` under `tasks` | `finally` tasks | `PipelineRun` status | Reason | | ----------------------------- | ----------- | -------------------- | ------ | -| all `PipelineTask` successful | all final tasks successful | `true` | `Succeeded` | -| all `PipelineTask` successful | one or more failure of final tasks | `false` | `Failed` | -| one or more `PipelineTask` [skipped](conditions.md) and rest successful | all final tasks successful | `true` | `Completed` | -| one or more `PipelineTask` [skipped](conditions.md) and rest successful | one or more failure of final tasks | `false` | `Failed` | -| single failure of `PipelineTask` | all final tasks successful | `false` | `failed` | -| single failure of `PipelineTask` | one or more failure of final tasks | `false` | `failed` | +| all `PipelineTask` successful | all `finally` tasks successful | `true` | `Succeeded` | +| all `PipelineTask` successful | one or more failure of `finally` tasks | `false` | `Failed` | +| one or more `PipelineTask` [skipped](conditions.md) and rest successful | all `finally` tasks successful | `true` | `Completed` | +| one or more `PipelineTask` [skipped](conditions.md) and rest successful | one or more failure of `finally` tasks | `false` | `Failed` | +| single failure of `PipelineTask` | all `finally` tasks successful | `false` | `failed` | +| single failure of `PipelineTask` | one or more failure of `finally` tasks | `false` | `failed` | Overall, `PipelineRun` state transitioning is explained below for respective scenarios: -* All `PipelineTask` and final tasks are successful: `Started` -> `Running` -> `Succeeded` +* All `PipelineTask` and `finally` tasks are successful: `Started` -> `Running` -> `Succeeded` * At least one `PipelineTask` skipped and rest successful: `Started` -> `Running` -> `Completed` -* One `PipelineTask` failed / one or more final tasks failed: `Started` -> `Running` -> `Failed` +* One `PipelineTask` failed / one or more `finally` tasks failed: `Started` -> `Running` -> `Failed` Please refer to the [table](pipelineruns.md#monitoring-execution-status) under Monitoring Execution Status to learn about what kind of events are triggered based on the `Pipelinerun` status. @@ -1212,16 +1211,16 @@ This kind of variable can have any one of the values from the following table: For an end-to-end example, see [`$(tasks.status)` usage in a `Pipeline`](../examples/v1beta1/pipelineruns/pipelinerun-task-execution-status.yaml). -### Guard `Finally Task` execution using `when` expressions +### Guard `finally` `Task` execution using `when` expressions -Similar to `Tasks`, `Finally Tasks` can be guarded using [`when` expressions](#guard-task-execution-using-when-expressions) -that operate on static inputs or variables. Like in `Tasks`, `when` expressions in `Finally Tasks` can operate on -`Parameters` and `Results`. Unlike in `Tasks`, `when` expressions in `Finally Tasks` can also operate on the [`Execution +Similar to `Tasks`, `finally` `Tasks` can be guarded using [`when` expressions](#guard-task-execution-using-when-expressions) +that operate on static inputs or variables. Like in `Tasks`, `when` expressions in `finally` `Tasks` can operate on +`Parameters` and `Results`. Unlike in `Tasks`, `when` expressions in `finally` `tasks` can also operate on the [`Execution Status`](#using-execution-status-of-pipelinetask) of `Tasks`. -#### `when` expressions using `Parameters` in `Finally Tasks` +#### `when` expressions using `Parameters` in `finally` `Tasks` -`when` expressions in `Finally Tasks` can utilize `Parameters` as demonstrated using [`golang-build`](https://github.com/tektoncd/catalog/tree/main/task/golang-build/0.1) +`when` expressions in `finally` `Tasks` can utilize `Parameters` as demonstrated using [`golang-build`](https://github.com/tektoncd/catalog/tree/main/task/golang-build/0.1) and [`send-to-channel-slack`](https://github.com/tektoncd/catalog/tree/main/task/send-to-channel-slack/0.1) Catalog `Tasks`: @@ -1258,9 +1257,9 @@ spec: value: true ``` -#### `when` expressions using `Results` in `Finally Tasks` +#### `when` expressions using `Results` in `finally` 'Tasks` -`when` expressions in `Finally Tasks` can utilize `Results`, as demonstrated using [`git-clone`](https://github.com/tektoncd/catalog/tree/main/task/git-clone/0.2) +`when` expressions in `finally` `tasks` can utilize `Results`, as demonstrated using [`git-clone`](https://github.com/tektoncd/catalog/tree/main/task/git-clone/0.2) and [`github-add-comment`](https://github.com/tektoncd/catalog/tree/main/task/github-add-comment/0.2) Catalog `Tasks`: ```yaml @@ -1290,13 +1289,13 @@ spec: value: 54dd3984affab47f3018852e61a1a6f9946ecfa ``` -If the `when` expressions in a `Finally Task` use `Results` from a skipped or failed non-finally `Tasks`, then the -`Finally Task` would also be skipped and be included in the list of `Skipped Tasks` in the `Status`, [similarly to when using -`Results` in other parts of the `Finally Task`](#consuming-task-execution-results-in-finally). +If the `when` expressions in a `finally` `task` use `Results` from a skipped or failed non-finally `Tasks`, then the +`finally` `task` would also be skipped and be included in the list of `Skipped Tasks` in the `Status`, [similarly to when using +`Results` in other parts of the `finally` `task`](#consuming-task-execution-results-in-finally). -#### `when` expressions using `Execution Status` of `PipelineTask` in `Finally Tasks` +#### `when` expressions using `Execution Status` of `PipelineTask` in `finally` `tasks` -`when` expressions in `Finally Tasks` can utilize [`Execution Status` of `PipelineTasks`](#using-execution-status-of-pipelinetask), +`when` expressions in `finally` `tasks` can utilize [`Execution Status` of `PipelineTasks`](#using-execution-status-of-pipelinetask), as demonstrated using [`golang-build`](https://github.com/tektoncd/catalog/tree/main/task/golang-build/0.1) and [`send-to-channel-slack`](https://github.com/tektoncd/catalog/tree/main/task/send-to-channel-slack/0.1) Catalog `Tasks`: @@ -1325,9 +1324,9 @@ spec: For an end-to-end example, see [PipelineRun with `when` expressions](../examples/v1beta1/pipelineruns/pipelinerun-with-when-expressions.yaml). -#### `when` expressions using `Aggregate Execution Status` of `Tasks` in `Finally Tasks` +#### `when` expressions using `Aggregate Execution Status` of `Tasks` in `finally` `tasks` -`when` expressions in `Finally Tasks` can utilize +`when` expressions in `finally` `tasks` can utilize [`Aggregate Execution Status` of `Tasks`](#using-aggregate-execution-status-of-all-tasks) as demonstrated: ```yaml @@ -1345,11 +1344,11 @@ For an end-to-end example, see [PipelineRun with `when` expressions](../examples ### Known Limitations -#### Specifying `Resources` in Final Tasks +#### Specifying `Resources` in `finally` tasks Similar to `tasks`, you can use [PipelineResources](#specifying-resources) as inputs and outputs for -final tasks in the Pipeline. The only difference here is, final tasks with an input resource can not have a `from` clause -like a `PipelineTask` from `tasks` section. For example: +`finally` tasks in the Pipeline. The only difference here is, final tasks with an input resource can not have a `from` +clause like a `PipelineTask` from `tasks` section. For example: ```yaml spec: @@ -1376,21 +1375,21 @@ spec: - tests ``` -#### Cannot configure the Final Task execution order +#### Cannot configure the `finally` task execution order -It's not possible to configure or modify the execution order of the final tasks. Unlike `Tasks` in a `Pipeline`, -all final tasks run simultaneously and start executing once all `PipelineTasks` under `tasks` have settled which means -no `runAfter` can be specified in final tasks. +It's not possible to configure or modify the execution order of the `finally` tasks. Unlike `Tasks` in a `Pipeline`, +all `finally` tasks run simultaneously and start executing once all `PipelineTasks` under `tasks` have settled which means +no `runAfter` can be specified in `finally` tasks. -#### Cannot specify execution `Conditions` in Final Tasks +#### Cannot specify execution `Conditions` in `finally` tasks `Tasks` in a `Pipeline` can be configured to run only if some conditions are satisfied using `conditions`. But the -final tasks are guaranteed to be executed after all `PipelineTasks` therefore no `conditions` can be specified in -final tasks. +`finally` tasks are guaranteed to be executed after all `PipelineTasks` therefore no `conditions` can be specified in +`finally` tasks. #### Cannot configure `Pipeline` result with `finally` -Final tasks can emit `Results` but results emitted from the final tasks can not be configured in the +`finally` tasks can emit `Results` but results emitted from the `finally` tasks can not be configured in the [Pipeline Results](#configuring-execution-results-at-the-pipeline-level). We are working on adding support for this (tracked in issue [#2710](https://github.com/tektoncd/pipeline/issues/2710)).