Graceful Pipeline Run Termination

The implementation of TEP-0058: Graceful Pipeline Run Termination.

The new `spec.Status` values:

- `StoppedRunFinally` - To "stop" (i.e. let the tasks complete, then execute finally tasks) a Pipeline
- `CancelledRunFinally` - To "cancel" (i.e. interrupt any executing non finally tasks, then execute finally tasks)
- `Cancelled` - Same as today's `PipelineRunCancelled` - i.e. interrupt any executing tasks without running finally tasks

`PipelineRunCancelled` is deprecated (replaced by `Cancelled`)

New features hidden by alpha API fields flag.

Author: rafalbigaj

docs/pipelineruns.md

@@ -525,8 +525,44 @@ Task Runs:
 ## Cancelling a `PipelineRun`
 
 To cancel a `PipelineRun` that's currently executing, update its definition
-to mark it as cancelled. When you do so, the spawned `TaskRuns` are also marked
-as cancelled and all associated `Pods` are deleted. For example:
+to mark it as "Cancelled". When you do so, the spawned `TaskRuns` are also marked
+as cancelled and all associated `Pods` are deleted. Pending final tasks are not scheduled. 
+For example:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  name: go-example-git
+spec:
+  # […]
+  status: "Cancelled"
+```
+
+## Gracefully cancelling a `PipelineRun`
+
+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. 
+For example:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  name: go-example-git
+spec:
+  # […]
+  status: "CancelledRunFinally"
+```
+
+
+## Gracefully stopping a `PipelineRun`
+
+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.
+For example:
 
 ```yaml
 apiVersion: tekton.dev/v1beta1
@@ -535,7 +571,7 @@ metadata:
   name: go-example-git
 spec:
   # […]
-  status: "PipelineRunCancelled"
+  status: "StoppedRunFinally"
 ```
 
 ## Pending `PipelineRuns`

internal/builder/v1beta1/pipeline.go

@@ -115,12 +115,27 @@ func PipelineDescription(desc string) PipelineSpecOp {
 	}
 }
 
-// PipelineRunCancelled sets the status to cancel the PipelineRunSpec.
+// PipelineRunCancelled sets the status to Cancelled in the PipelineRunSpec.
 func PipelineRunCancelled(spec *v1beta1.PipelineRunSpec) {
 	spec.Status = v1beta1.PipelineRunSpecStatusCancelled
 }
 
-// PipelineRunPending sets the status to pending to the PipelineRunSpec.
+// PipelineRunCancelledDeprecated sets the status to PipelineRunCancelled in the PipelineRunSpec.
+func PipelineRunCancelledDeprecated(spec *v1beta1.PipelineRunSpec) {
+	spec.Status = v1beta1.PipelineRunSpecStatusCancelledDeprecated
+}
+
+// PipelineRunCancelledRunFinally sets the status to cancel and run finally in the PipelineRunSpec.
+func PipelineRunCancelledRunFinally(spec *v1beta1.PipelineRunSpec) {
+	spec.Status = v1beta1.PipelineRunSpecStatusCancelledRunFinally
+}
+
+// PipelineRunStoppedRunFinally sets the status to stop and run finally in the PipelineRunSpec.
+func PipelineRunStoppedRunFinally(spec *v1beta1.PipelineRunSpec) {
+	spec.Status = v1beta1.PipelineRunSpecStatusStoppedRunFinally
+}
+
+// PipelineRunPending sets the status to pending in the PipelineRunSpec.
 func PipelineRunPending(spec *v1beta1.PipelineRunSpec) {
 	spec.Status = v1beta1.PipelineRunSpecStatusPending
 }

pkg/apis/pipeline/v1alpha1/pipelinerun_types.go

@@ -101,7 +101,7 @@ type PipelineRunSpecStatus = v1beta1.PipelineRunSpecStatus
 const (
 	// PipelineRunSpecStatusCancelled indicates that the user wants to cancel the task,
 	// if not already cancelled or terminated
-	PipelineRunSpecStatusCancelled = v1beta1.PipelineRunSpecStatusCancelled
+	PipelineRunSpecStatusCancelled = v1beta1.PipelineRunSpecStatusCancelledDeprecated
 )
 
 // PipelineResourceRef can be used to refer to a specific instance of a Resource

pkg/apis/pipeline/v1beta1/pipelinerun_types.go

@@ -85,7 +85,17 @@ func (pr *PipelineRun) HasStarted() bool {
 
 // IsCancelled returns true if the PipelineRun's spec status is set to Cancelled state
 func (pr *PipelineRun) IsCancelled() bool {
-	return pr.Spec.Status == PipelineRunSpecStatusCancelled
+	return pr.Spec.Status == PipelineRunSpecStatusCancelled || pr.Spec.Status == PipelineRunSpecStatusCancelledDeprecated
+}
+
+// IsGracefullyCancelled returns true if the PipelineRun's spec status is set to CancelledRunFinally state
+func (pr *PipelineRun) IsGracefullyCancelled() bool {
+	return pr.Spec.Status == PipelineRunSpecStatusCancelledRunFinally
+}
+
+// IsGracefullyStopped returns true if the PipelineRun's spec status is set to StoppedRunFinally state
+func (pr *PipelineRun) IsGracefullyStopped() bool {
+	return pr.Spec.Status == PipelineRunSpecStatusStoppedRunFinally
 }
 
 func (pr *PipelineRun) GetTimeout(ctx context.Context) time.Duration {
@@ -193,9 +203,22 @@ type PipelineRunSpec struct {
 type PipelineRunSpecStatus string
 
 const (
+	// Deprecated: "PipelineRunCancelled" indicates that the user wants to cancel the task,
+	// if not already cancelled or terminated (replaced by "Cancelled")
+	PipelineRunSpecStatusCancelledDeprecated = "PipelineRunCancelled"
+
 	// PipelineRunSpecStatusCancelled indicates that the user wants to cancel the task,
 	// if not already cancelled or terminated
-	PipelineRunSpecStatusCancelled = "PipelineRunCancelled"
+	PipelineRunSpecStatusCancelled = "Cancelled"
+
+	// PipelineRunSpecStatusCancelledRunFinally indicates that the user wants to cancel the pipeline run,
+	// if not already cancelled or terminated, but ensure finally is run normally
+	PipelineRunSpecStatusCancelledRunFinally = "CancelledRunFinally"
+
+	// PipelineRunSpecStatusStoppedRunFinally indicates that the user wants to stop the pipeline run,
+	// wait for already running tasks to be completed and run finally
+	// if not already cancelled or terminated
+	PipelineRunSpecStatusStoppedRunFinally = "StoppedRunFinally"
 
 	// PipelineRunSpecStatusPending indicates that the user wants to postpone starting a PipelineRun
 	// until some condition is met

pkg/apis/pipeline/v1beta1/pipelinerun_validation.go

@@ -82,11 +82,7 @@ func (ps *PipelineRunSpec) Validate(ctx context.Context) (errs *apis.FieldError)
 		}
 	}
 
-	if ps.Status != "" {
-		if ps.Status != PipelineRunSpecStatusCancelled && ps.Status != PipelineRunSpecStatusPending {
-			errs = errs.Also(apis.ErrInvalidValue(fmt.Sprintf("%s should be %s or %s", ps.Status, PipelineRunSpecStatusCancelled, PipelineRunSpecStatusPending), "status"))
-		}
-	}
+	errs = errs.Also(validateSpecStatus(ps.Status, cfg))
 
 	if ps.Workspaces != nil {
 		wsNames := make(map[string]int)
@@ -101,3 +97,30 @@ func (ps *PipelineRunSpec) Validate(ctx context.Context) (errs *apis.FieldError)
 
 	return errs
 }
+
+func validateSpecStatus(status PipelineRunSpecStatus, cfg *config.Config) *apis.FieldError {
+	alphaAPIFieldsEnabled := cfg.FeatureFlags.EnableAPIFields == config.AlphaAPIFields
+	switch status {
+	case "":
+		return nil
+	case PipelineRunSpecStatusPending,
+		PipelineRunSpecStatusCancelledDeprecated:
+		return nil
+	case PipelineRunSpecStatusCancelled,
+		PipelineRunSpecStatusCancelledRunFinally,
+		PipelineRunSpecStatusStoppedRunFinally:
+		if alphaAPIFieldsEnabled {
+			return nil
+		}
+	}
+	if alphaAPIFieldsEnabled {
+		return apis.ErrInvalidValue(fmt.Sprintf("%s should be %s, %s, %s or %s", status,
+			PipelineRunSpecStatusCancelled,
+			PipelineRunSpecStatusCancelledRunFinally,
+			PipelineRunSpecStatusStoppedRunFinally,
+			PipelineRunSpecStatusPending), "status")
+	}
+	return apis.ErrInvalidValue(fmt.Sprintf("%s should be %s or %s", status,
+		PipelineRunSpecStatusCancelledDeprecated,
+		PipelineRunSpecStatusPending), "status")
+}

pkg/apis/pipeline/v1beta1/pipelinerun_validation_test.go

@@ -91,7 +91,22 @@ func TestPipelineRun_Invalid(t *testing.T) {
 				Status: "PipelineRunCancell",
 			},
 		},
-		want: apis.ErrInvalidValue("PipelineRunCancell should be PipelineRunCancelled or PipelineRunPending", "spec.status"),
+		want: apis.ErrInvalidValue("PipelineRunCancell should be Cancelled, CancelledRunFinally, StoppedRunFinally or PipelineRunPending", "spec.status"),
+		wc:   enableAlphaAPIFields(t),
+	}, {
+		name: "alpha pipelinerun graceful cancel",
+		pr: v1beta1.PipelineRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pipelinelinename",
+			},
+			Spec: v1beta1.PipelineRunSpec{
+				PipelineRef: &v1beta1.PipelineRef{
+					Name: "prname",
+				},
+				Status: v1beta1.PipelineRunSpecStatusCancelled,
+			},
+		},
+		want: apis.ErrInvalidValue("Cancelled should be PipelineRunCancelled or PipelineRunPending", "spec.status"),
 	}, {
 		name: "use of bundle without the feature flag set",
 		pr: v1beta1.PipelineRun{
@@ -180,6 +195,7 @@ func TestPipelineRun_Validate(t *testing.T) {
 	tests := []struct {
 		name string
 		pr   v1beta1.PipelineRun
+		wc   func(context.Context) context.Context
 	}{{
 		name: "normal case",
 		pr: v1beta1.PipelineRun{
@@ -256,11 +272,70 @@ func TestPipelineRun_Validate(t *testing.T) {
 				},
 			},
 		},
+	}, {
+		name: "pipelinerun cancelled",
+		pr: v1beta1.PipelineRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pipelinerunname",
+			},
+			Spec: v1beta1.PipelineRunSpec{
+				Status: v1beta1.PipelineRunSpecStatusCancelled,
+				PipelineRef: &v1beta1.PipelineRef{
+					Name: "prname",
+				},
+			},
+		},
+		wc: enableAlphaAPIFields(t),
+	}, {
+		name: "pipelinerun cancelled deprecated",
+		pr: v1beta1.PipelineRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pipelinerunname",
+			},
+			Spec: v1beta1.PipelineRunSpec{
+				Status: v1beta1.PipelineRunSpecStatusCancelledDeprecated,
+				PipelineRef: &v1beta1.PipelineRef{
+					Name: "prname",
+				},
+			},
+		},
+	}, {
+		name: "pipelinerun gracefully cancelled",
+		pr: v1beta1.PipelineRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pipelinerunname",
+			},
+			Spec: v1beta1.PipelineRunSpec{
+				Status: v1beta1.PipelineRunSpecStatusCancelledRunFinally,
+				PipelineRef: &v1beta1.PipelineRef{
+					Name: "prname",
+				},
+			},
+		},
+		wc: enableAlphaAPIFields(t),
+	}, {
+		name: "pipelinerun gracefully stopped",
+		pr: v1beta1.PipelineRun{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "pipelinerunname",
+			},
+			Spec: v1beta1.PipelineRunSpec{
+				Status: v1beta1.PipelineRunSpecStatusStoppedRunFinally,
+				PipelineRef: &v1beta1.PipelineRef{
+					Name: "prname",
+				},
+			},
+		},
+		wc: enableAlphaAPIFields(t),
 	}}
 
 	for _, ts := range tests {
 		t.Run(ts.name, func(t *testing.T) {
-			if err := ts.pr.Validate(context.Background()); err != nil {
+			ctx := context.Background()
+			if ts.wc != nil {
+				ctx = ts.wc(ctx)
+			}
+			if err := ts.pr.Validate(ctx); err != nil {
 				t.Error(err)
 			}
 		})
@@ -380,3 +455,16 @@ func enableTektonOCIBundles(t *testing.T) func(context.Context) context.Context
 		return s.ToContext(ctx)
 	}
 }
+
+func enableAlphaAPIFields(t *testing.T) func(context.Context) context.Context {
+	return func(ctx context.Context) context.Context {
+		s := config.NewStore(logtesting.TestLogger(t))
+		s.OnConfigChanged(&corev1.ConfigMap{
+			ObjectMeta: metav1.ObjectMeta{Name: config.GetFeatureFlagsConfigName()},
+			Data: map[string]string{
+				"enable-api-fields": config.AlphaAPIFields,
+			},
+		})
+		return s.ToContext(ctx)
+	}
+}