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

The new `PipelineRun` condition reasons:

- `CancelledRunningFinally` - indicates that pipeline has been gracefully cancelled, but final tasks are now running
- `StoppedRunningFinally` - indicates that pipeline has been gracefully stopped, but final tasks are now running

Status `PipelineRunCancelled` is deprecated (replaced by `Cancelled`). The same applies to the condition reason.

New features hidden by alpha API fields flag.

Author: rafalbigaj

docs/pipelineruns.md

@@ -561,8 +561,9 @@ 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 "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. 
+For example:
 
 ```yaml
 apiVersion: tekton.dev/v1beta1
@@ -574,6 +575,46 @@ spec:
   status: "PipelineRunCancelled"
 ```
 
+Warning: "PipelineRunCancelled" status is deprecated and would be removed in V1, please use "Cancelled" instead.  
+
+## Gracefully cancelling a `PipelineRun`
+
+[Graceful pipeline run termination](https://github.com/tektoncd/community/blob/main/teps/0058-graceful-pipeline-run-termination.md)
+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. 
+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
+kind: PipelineRun
+metadata:
+  name: go-example-git
+spec:
+  # […]
+  status: "StoppedRunFinally"
+```
+
 ## Pending `PipelineRuns`
 
 A `PipelineRun` can be created as a "pending" `PipelineRun` meaning that it will not actually be started until the pending status is cleared.

go.sum

@@ -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
 }

internal/builder/v1beta1/pipeline.go

@@ -469,6 +469,69 @@ func TestPipelineRunWithFinalTask(t *testing.T) {
 	}
 }
 
+func TestPipelineRunCancelled(t *testing.T) {
+	pipelineRun := tb.PipelineRun("pear", tb.PipelineRunNamespace("foo"),
+		tb.PipelineRunSpec("pears", tb.PipelineRunCancelled))
+
+	expectedPipelineRun := &v1beta1.PipelineRun{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "pear",
+			Namespace: "foo",
+		},
+		Spec: v1beta1.PipelineRunSpec{
+			PipelineRef: &v1beta1.PipelineRef{Name: "pears"},
+			Status:      v1beta1.PipelineRunSpecStatusCancelled,
+			Timeout:     &metav1.Duration{Duration: 1 * time.Hour},
+		},
+	}
+
+	if diff := cmp.Diff(expectedPipelineRun, pipelineRun); diff != "" {
+		t.Fatalf("PipelineRun diff -want, +got: %s", diff)
+	}
+}
+
+func TestPipelineRunCancelledRunFinally(t *testing.T) {
+	pipelineRun := tb.PipelineRun("pear", tb.PipelineRunNamespace("foo"),
+		tb.PipelineRunSpec("pears", tb.PipelineRunCancelledRunFinally))
+
+	expectedPipelineRun := &v1beta1.PipelineRun{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "pear",
+			Namespace: "foo",
+		},
+		Spec: v1beta1.PipelineRunSpec{
+			PipelineRef: &v1beta1.PipelineRef{Name: "pears"},
+			Status:      v1beta1.PipelineRunSpecStatusCancelledRunFinally,
+			Timeout:     &metav1.Duration{Duration: 1 * time.Hour},
+		},
+	}
+
+	if diff := cmp.Diff(expectedPipelineRun, pipelineRun); diff != "" {
+		t.Fatalf("PipelineRun diff -want, +got: %s", diff)
+	}
+}
+
+func TestPipelineRunStoppedRunFinally(t *testing.T) {
+	pipelineRun := tb.PipelineRun("pear", tb.PipelineRunNamespace("foo"),
+		tb.PipelineRunSpec("pears", tb.PipelineRunStoppedRunFinally))
+
+	expectedPipelineRun := &v1beta1.PipelineRun{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "pear",
+			Namespace: "foo",
+		},
+		Spec: v1beta1.PipelineRunSpec{
+			PipelineRef: &v1beta1.PipelineRef{Name: "pears"},
+			Status:      v1beta1.PipelineRunSpecStatusStoppedRunFinally,
+			Timeout:     &metav1.Duration{Duration: 1 * time.Hour},
+		},
+	}
+
+	if diff := cmp.Diff(expectedPipelineRun, pipelineRun); diff != "" {
+		t.Fatalf("PipelineRun diff -want, +got: %s", diff)
+	}
+}
+
 func getTaskSpec() v1beta1.TaskSpec {
 	return v1beta1.TaskSpec{
 		Steps: []v1beta1.Step{{Container: corev1.Container{

internal/builder/v1beta1/pipeline_test.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/v1alpha1/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 {
@@ -216,9 +226,22 @@ type TimeoutFields 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
@@ -271,6 +294,12 @@ const (
 	// PipelineRunReasonStopping indicates that no new Tasks will be scheduled by the controller, and the
 	// pipeline will stop once all running tasks complete their work
 	PipelineRunReasonStopping PipelineRunReason = "PipelineRunStopping"
+	// PipelineRunReasonCancelledRunningFinally indicates that pipeline has been gracefully cancelled
+	// and no new Tasks will be scheduled by the controller, but final tasks are now running
+	PipelineRunReasonCancelledRunningFinally PipelineRunReason = "CancelledRunningFinally"
+	// PipelineRunReasonStoppedRunningFinally indicates that pipeline has been gracefully stopped
+	// and no new Tasks will be scheduled by the controller, but final tasks are now running
+	PipelineRunReasonStoppedRunningFinally PipelineRunReason = "StoppedRunningFinally"
 )
 
 func (t PipelineRunReason) String() string {

pkg/apis/pipeline/v1beta1/pipelinerun_types.go

@@ -135,6 +135,28 @@ func TestPipelineRunIsCancelled(t *testing.T) {
 	}
 }
 
+func TestPipelineRunIsGracefullyCancelled(t *testing.T) {
+	pr := &v1beta1.PipelineRun{
+		Spec: v1beta1.PipelineRunSpec{
+			Status: v1beta1.PipelineRunSpecStatusCancelledRunFinally,
+		},
+	}
+	if !pr.IsGracefullyCancelled() {
+		t.Fatal("Expected pipelinerun status to be gracefully cancelled")
+	}
+}
+
+func TestPipelineRunIsGracefullyStopped(t *testing.T) {
+	pr := &v1beta1.PipelineRun{
+		Spec: v1beta1.PipelineRunSpec{
+			Status: v1beta1.PipelineRunSpecStatusStoppedRunFinally,
+		},
+	}
+	if !pr.IsGracefullyStopped() {
+		t.Fatal("Expected pipelinerun status to be gracefully stopped")
+	}
+}
+
 func TestPipelineRunHasVolumeClaimTemplate(t *testing.T) {
 	pr := &v1beta1.PipelineRun{
 		Spec: v1beta1.PipelineRunSpec{

pkg/apis/pipeline/v1beta1/pipelinerun_types_test.go

@@ -115,11 +115,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(ctx, ps.Status))
 
 	if ps.Workspaces != nil {
 		wsNames := make(map[string]int)
@@ -135,6 +131,32 @@ func (ps *PipelineRunSpec) Validate(ctx context.Context) (errs *apis.FieldError)
 	return errs
 }
 
+func validateSpecStatus(ctx context.Context, status PipelineRunSpecStatus) *apis.FieldError {
+	switch status {
+	case "":
+		return nil
+	case PipelineRunSpecStatusPending,
+		PipelineRunSpecStatusCancelledDeprecated:
+		return nil
+	case PipelineRunSpecStatusCancelled,
+		PipelineRunSpecStatusCancelledRunFinally,
+		PipelineRunSpecStatusStoppedRunFinally:
+		return ValidateEnabledAPIFields(ctx, "graceful termination", "alpha")
+	}
+
+	cfg := config.FromContextOrDefaults(ctx)
+	if cfg.FeatureFlags.EnableAPIFields == config.AlphaAPIFields {
+		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")
+}
+
 func validateTimeoutDuration(field string, d *metav1.Duration) (errs *apis.FieldError) {
 	if d != nil && d.Duration < 0 {
 		fieldPath := fmt.Sprintf("timeouts.%s", field)