diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md index a68a47d1b0a..d7705d40f7a 100644 --- a/docs/pipelineruns.md +++ b/docs/pipelineruns.md @@ -562,7 +562,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 and all associated `Pods` are deleted. Pending final tasks are not scheduled. +as cancelled and all associated `Pods` are deleted. Pending finally tasks are not scheduled. For example: ```yaml @@ -584,7 +584,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 and all associated `Pods` are deleted. Final tasks are scheduled normally. +as cancelled and all associated `Pods` are deleted. Finally tasks are scheduled normally. For example: ```yaml @@ -602,7 +602,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 20c4531badd..26d6378f343 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -27,8 +27,8 @@ 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) @@ -39,9 +39,9 @@ weight: 400 - [`WhenExpressions` using `Execution Status` of `PipelineTask` in `Finally Tasks`](#whenexpressions-using-execution-status-of-pipelinetask-in-finally-tasks) - [`WhenExpressions` using `Aggregate Execution Status` of `Tasks` in `Finally Tasks`](#whenexpressions-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) @@ -783,9 +783,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: @@ -801,11 +801,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 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: @@ -834,9 +834,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: @@ -855,7 +855,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: @@ -869,19 +869,19 @@ 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 `clone-app-repo` failed or skipped with [when expression](#guard-task-execution-using-whenexpressions) 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 +`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`: @@ -893,20 +893,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. @@ -1113,11 +1113,11 @@ For an end-to-end example, see [PipelineRun with WhenExpressions](../examples/v1 ### 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: @@ -1144,21 +1144,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)).