From 361b9ae200e99601294fbaf894801ce84d8238e5 Mon Sep 17 00:00:00 2001 From: Jerop Date: Wed, 9 Feb 2022 12:01:57 -0500 Subject: [PATCH] [TEP-0059] Scope `when` expressions to `Task` only In [TEP-0007: Conditions Beta][tep-0007], we introduced `when` expressions to guard execution of `Tasks` in `Pipelines`. To align with `Conditions`, we set scope of `when` expressions to the guarded `Task` and its dependent `Tasks`. In [TEP-0059: Skipping Strategies][tep-0059], we proposed changing the scope of `when` expressions to the guarded `Task` only. This was implemented in https://github.com/tektoncd/pipeline/pull/4085. We provided a feature flag, `scope-when-expressions-to-task`, to support migration. It defaulted to `false` for 9 months per our [Beta API compatibility policy][policy], meaning that we continued to guard the `Task` and its dependent `Tasks`. In this change, we flip the flag to `true` to guard the `Task` only by default. [tep-0007]: https://github.com/tektoncd/community/blob/main/teps/0007-conditions-beta.md [tep-0059]: https://github.com/tektoncd/community/blob/main/teps/0059-skipping-strategies.md [policy]: https://github.com/tektoncd/pipeline/blob/main/api_compatibility_policy.md --- config/config-feature-flags.yaml | 2 +- docs/deprecations.md | 1 - docs/install.md | 2 +- docs/pipelines.md | 30 ++++++++++++------- pkg/apis/config/feature_flags.go | 2 +- .../pipelinerun/pipelinerun_test.go | 6 ++-- 6 files changed, 25 insertions(+), 18 deletions(-) diff --git a/config/config-feature-flags.yaml b/config/config-feature-flags.yaml index 870ceadd409..1e55e3b6251 100644 --- a/config/config-feature-flags.yaml +++ b/config/config-feature-flags.yaml @@ -84,4 +84,4 @@ data: enable-api-fields: "stable" # Setting this flag to "true" scopes when expressions to guard a Task only # instead of a Task and its dependent Tasks. - scope-when-expressions-to-task: "false" + scope-when-expressions-to-task: "true" diff --git a/docs/deprecations.md b/docs/deprecations.md index a3061c33378..2c9b5790b04 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -25,6 +25,5 @@ being deprecated. | [`Conditions` CRD is deprecated and will be removed. Use `when` expressions instead.](https://github.com/tektoncd/community/blob/main/teps/0007-conditions-beta.md) | [v0.16.0](https://github.com/tektoncd/pipeline/releases/tag/v0.16.0) | Alpha | Nov 02 2020 | | [The `disable-home-env-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/2013) | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | Beta | February 10 2022 | | [The `disable-working-dir-overwrite` flag will be removed](https://github.com/tektoncd/pipeline/issues/1836) | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | Beta | February 10 2022 | -| [The `scope-when-expressions-to-task` flag will be flipped from "false" to "true"](https://github.com/tektoncd/pipeline/issues/4461) | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0) | Beta | February 10 2022 | | [The `scope-when-expressions-to-task` flag will be removed](https://github.com/tektoncd/pipeline/issues/4461) | [v0.27.0](https://github.com/tektoncd/pipeline/releases/tag/v0.27.0) | Beta | March 10 2022 | | [`PipelineResources` are deprecated.](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md) | [v0.30.0](https://github.com/tektoncd/pipeline/releases/tag/v0.30.0) | Alpha | Dec 20 2021 | diff --git a/docs/install.md b/docs/install.md index 143ad7de2c6..cea414510f6 100644 --- a/docs/install.md +++ b/docs/install.md @@ -378,7 +378,7 @@ most stable features to be used. Set it to "alpha" to allow [alpha features](#alpha-features) to be used. - `scope-when-expressions-to-task`: set this flag to "true" to scope `when` expressions to guard a `Task` only. Set it - to "false" to guard a `Task` and its dependent `Tasks`. It defaults to "false". For more information, see [guarding + to "false" to guard a `Task` and its dependent `Tasks`. It defaults to "true". For more information, see [guarding `Task` execution using `when` expressions](pipelines.md#guard-task-execution-using-whenexpressions). For example: diff --git a/docs/pipelines.md b/docs/pipelines.md index de9bae82891..86ffe7ca74a 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -496,14 +496,24 @@ There are a lot of scenarios where `when` expressions can be really useful. Some #### Guarding a `Task` and its dependent `Tasks` -When `when` expressions evaluate to `False`, the `Task` and its dependent `Tasks` will be skipped by default while the -rest of the `Pipeline` will execute. Dependencies between `Tasks` can be either ordering ([`runAfter`](https://github.com/tektoncd/pipeline/blob/main/docs/pipelines.md#using-the-runafter-parameter)) +> :warning: **Scoping `when` expressions to a `Task` and its dependent `Tasks` is deprecated.** +> +> Consider migrating to scoping `when` expressions to the guarded `Task` only instead. +> Read more in the [documentation](#guarding-a-task-only) and [TEP-0059: Skipping Strategies][tep-0059]. +> +[tep-0059]: https://github.com/tektoncd/community/blob/main/teps/0059-skipping-strategies.md + +To guard a `Task` and its dependent `Tasks`, set the global default scope of `when` expressions to `Task` using the +`scope-when-expressions-to-task` field in [`config/config-feature-flags.yaml`](install.md#customizing-the-pipelines-controller-behavior) +by changing it to "false". + +When `when` expressions evaluate to `False`, and `scope-when-expressions-to-task` is set to "false", the `Task` and +its dependent `Tasks` will be skipped while the rest of the `Pipeline` will execute. Dependencies between `Tasks` can +be either ordering ([`runAfter`](https://github.com/tektoncd/pipeline/blob/main/docs/pipelines.md#using-the-runafter-parameter)) or resource (e.g. [`Results`](https://github.com/tektoncd/pipeline/blob/main/docs/pipelines.md#using-results)) dependencies, as further described in [configuring execution order](#configuring-the-task-execution-order). The global -default scope of `when` expressions is set to a `Task` and its dependent`Tasks`; `scope-when-expressions-to-task` field -in [`config/config-feature-flags.yaml`](install.md#customizing-the-pipelines-controller-behavior) defaults to "false". - -**Note:** Scoping `when` expressions to a `Task` and its dependent `Tasks` is deprecated +default scope of `when` expressions is set to a `Task` only; `scope-when-expressions-to-task` field in +[`config/config-feature-flags.yaml`](install.md#customizing-the-pipelines-controller-behavior) defaults to "true". To guard a `Task` and its dependent Tasks: - cascade the `when` expressions to the specific dependent `Tasks` to be guarded as well @@ -646,9 +656,7 @@ tasks: #### Guarding a `Task` only -To guard a `Task` only and unblock execution of its dependent `Tasks`, set the global default scope of `when` expressions -to `Task` using the `scope-when-expressions-to-task` field in [`config/config-feature-flags.yaml`](install.md#customizing-the-pipelines-controller-behavior) -by changing it to "true" +When `when` expressions evaluate to `False`, the `Task` will be skipped and: - The ordering-dependent `Tasks` will be executed - The resource-dependent `Tasks` (and their dependencies) will be skipped because of missing `Results` from the skipped parent `Task`. When we add support for [default `Results`](https://github.com/tektoncd/community/pull/240), then the @@ -657,6 +665,8 @@ by changing it to "true" to handle the execution of the child `Task` in case the expected file is missing from the `Workspace` because the guarded parent `Task` is skipped. +On the other hand, the rest of the `Pipeline` will continue executing. + ``` tests | @@ -706,7 +716,7 @@ tasks: name: slack-msg ``` -With `when` expressions scoped to `Task`, if `manual-approval` is skipped, execution of it's dependent `Tasks` +With `when` expressions scoped to `Task`, if `manual-approval` is skipped, execution of its dependent `Tasks` (`slack-msg`, `build-image` and `deploy-image`) would be unblocked regardless: - `build-image` and `deploy-image` should be executed successfully - `slack-msg` will be skipped because it is missing the `approver` `Result` from `manual-approval` diff --git a/pkg/apis/config/feature_flags.go b/pkg/apis/config/feature_flags.go index 021ceaea8ce..f890c3b1ddd 100644 --- a/pkg/apis/config/feature_flags.go +++ b/pkg/apis/config/feature_flags.go @@ -47,7 +47,7 @@ const ( // DefaultEnableCustomTasks is the default value for "enable-custom-tasks". DefaultEnableCustomTasks = false // DefaultScopeWhenExpressionsToTask is the default value for "scope-when-expressions-to-task". - DefaultScopeWhenExpressionsToTask = false + DefaultScopeWhenExpressionsToTask = true // DefaultEnableAPIFields is the default value for "enable-api-fields". DefaultEnableAPIFields = StableAPIFields diff --git a/pkg/reconciler/pipelinerun/pipelinerun_test.go b/pkg/reconciler/pipelinerun/pipelinerun_test.go index 9cc85fdfcd3..8e71b899ac9 100644 --- a/pkg/reconciler/pipelinerun/pipelinerun_test.go +++ b/pkg/reconciler/pipelinerun/pipelinerun_test.go @@ -5036,7 +5036,7 @@ func TestReconcileWithWhenExpressionsWithTaskResults(t *testing.T) { wantEvents := []string{ "Normal Started", - "Normal Running Tasks Completed: 1 \\(Failed: 0, Cancelled 0\\), Incomplete: 1, Skipped: 2", + "Normal Running Tasks Completed: 1 \\(Failed: 0, Cancelled 0\\), Incomplete: 2, Skipped: 1", } pipelineRun, clients := prt.reconcileRun("foo", "test-pipeline-run-different-service-accs", wantEvents, false) @@ -5089,14 +5089,12 @@ func TestReconcileWithWhenExpressionsWithTaskResults(t *testing.T) { Operator: "in", Values: []string{"missing"}, }}, - }, { - Name: "d-task", }} if d := cmp.Diff(actualSkippedTasks, expectedSkippedTasks); d != "" { t.Errorf("expected to find Skipped Tasks %v. Diff %s", expectedSkippedTasks, diff.PrintWantGot(d)) } - skippedTasks := []string{"c-task", "d-task"} + skippedTasks := []string{"c-task"} for _, skippedTask := range skippedTasks { labelSelector := fmt.Sprintf("tekton.dev/pipelineTask=%s,tekton.dev/pipelineRun=test-pipeline-run-different-service-accs", skippedTask) actualSkippedTask, err := clients.Pipeline.TektonV1beta1().TaskRuns("foo").List(prt.TestAssets.Ctx, metav1.ListOptions{