WIP: (TEP 0097) debug: breakpoint after,before step execution

cmd/entrypoint/main.go

@@ -54,6 +54,8 @@ var (
 	stdoutPath          = flag.String("stdout_path", "", "If specified, file to copy stdout to")
 	stderrPath          = flag.String("stderr_path", "", "If specified, file to copy stderr to")
 	breakpointOnFailure = flag.Bool("breakpoint_on_failure", false, "If specified, expect steps to not skip on failure")
+	breakpointBefore    = flag.Bool("breakpoint_before", false, "If specified, expect steps to not skip before the specified step")
+	breakpointAfter     = flag.Bool("breakpoint_after", false, "If specified, expect steps to not skip after the specified step")
 	onError             = flag.String("on_error", "", "Set to \"continue\" to ignore an error and continue when a container terminates with a non-zero exit code."+
 		" Set to \"stopAndFail\" to declare a failure with a step error and stop executing the rest of the steps.")
 	stepMetadataDir        = flag.String("step_metadata_dir", "", "If specified, create directory to store the step metadata e.g. /tekton/steps/<step-name>/")
@@ -67,9 +69,9 @@ const (
 	breakpointExitSuffix       = ".breakpointexit"
 )
 
-func checkForBreakpointOnFailure(e entrypoint.Entrypointer, breakpointExitPostFile string) {
-	if e.BreakpointOnFailure {
-		if waitErr := e.Waiter.Wait(context.Background(), breakpointExitPostFile, false, false); waitErr != nil {
+func checkForBreakpoint(e entrypoint.Entrypointer, breakpointExitPostFile string) {
+	if e.BreakpointOnFailure || e.BreakpointAfter || e.BreakpointBefore {
+		if waitErr := e.Waiter.Wait(context.Background(), breakpointExitPostFile, false, e.BreakpointOnFailure); waitErr != nil {
 			log.Println("error occurred while waiting for " + breakpointExitPostFile + " : " + waitErr.Error())
 		}
 		// get exitcode from .breakpointexit
@@ -163,6 +165,8 @@ func main() {
 		StepResults:            strings.Split(*stepResults, ","),
 		Timeout:                timeout,
 		BreakpointOnFailure:    *breakpointOnFailure,
+		BreakpointAfter:        *breakpointAfter,
+		BreakpointBefore:       *breakpointBefore,
 		OnError:                *onError,
 		StepMetadataDir:        *stepMetadataDir,
 		SpireWorkloadAPI:       spireWorkloadAPI,
@@ -174,9 +178,10 @@ func main() {
 	if err := credentials.CopyCredsToHome(credentials.CredsInitCredentials); err != nil {
 		log.Printf("non-fatal error copying credentials: %q", err)
 	}
-
+	breakpointExitPostFile := e.PostFile + breakpointExitSuffix
+	// check if there is a breakpoint set before the entrypoint runs
+	checkForBreakpoint(e, breakpointExitPostFile)
 	if err := e.Go(); err != nil {
-		breakpointExitPostFile := e.PostFile + breakpointExitSuffix
 		switch t := err.(type) { //nolint:errorlint // checking for multiple types with errors.As is ugly.
 		case skipError:
 			log.Print("Skipping step because a previous step failed")
@@ -201,7 +206,8 @@ func main() {
 			// in both cases has an ExitStatus() method with the
 			// same signature.
 			if status, ok := t.Sys().(syscall.WaitStatus); ok {
-				checkForBreakpointOnFailure(e, breakpointExitPostFile)
+				// check if there is a breakpoint set after the command errors out
+				checkForBreakpoint(e, breakpointExitPostFile)
 				// ignore a step error i.e. do not exit if a container terminates with a non-zero exit code when onError is set to "continue"
 				if e.OnError != entrypoint.ContinueOnError {
 					os.Exit(status.ExitStatus())
@@ -212,7 +218,8 @@ func main() {
 				log.Fatalf("Error executing command (ExitError): %v", err)
 			}
 		default:
-			checkForBreakpointOnFailure(e, breakpointExitPostFile)
+			// check if there is a breakpoint set after the command has finished running
+			checkForBreakpoint(e, breakpointExitPostFile)
 			log.Fatalf("Error executing command: %v", err)
 		}
 	}

docs/pipeline-api.md

@@ -4869,6 +4869,26 @@ string
 failed step will not exit</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>afterBreakpoints</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+</td>
+</tr>
+<tr>
+<td>
+<code>beforeBreakpoints</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.TaskKind">TaskKind
@@ -13957,6 +13977,28 @@ string
 failed step will not exit</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>beforeSteps</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+</td>
+</tr>
+<tr>
+<td>
+<code>afterSteps</code><br/>
+<em>
+[]string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1beta1.TaskKind">TaskKind

pkg/apis/pipeline/v1/swagger.json

@@ -1729,6 +1729,20 @@
       "description": "TaskBreakpoints defines the breakpoint config for a particular Task",
       "type": "object",
       "properties": {
+        "afterBreakpoints": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "default": ""
+          }
+        },
+        "beforeBreakpoints": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "default": ""
+          }
+        },
         "onFailure": {
           "description": "if enabled, pause TaskRun on failure of a step failed step will not exit",
           "type": "string"

pkg/apis/pipeline/v1/taskrun_types.go

@@ -16,6 +16,7 @@ package v1
 import (
 	"context"
 	"fmt"
+	"k8s.io/utils/strings/slices"
 	"time"
 
 	"github.com/tektoncd/pipeline/pkg/apis/config"
@@ -119,7 +120,9 @@ type TaskBreakpoints struct {
 	// if enabled, pause TaskRun on failure of a step
 	// failed step will not exit
 	// +optional
-	OnFailure string `json:"onFailure,omitempty"`
+	OnFailure         string   `json:"onFailure,omitempty"`
+	AfterBreakpoints  []string `json:"afterBreakpoints,omitempty"`
+	BeforeBreakpoints []string `json:"beforeBreakpoints,omitempty"`
 }
 
 // NeedsDebugOnFailure return true if the TaskRun is configured to debug on failure
@@ -130,14 +133,19 @@ func (trd *TaskRunDebug) NeedsDebugOnFailure() bool {
 	return trd.Breakpoints.OnFailure == EnabledOnFailureBreakpoint
 }
 
-// StepNeedsDebug return true if the step is configured to debug
-func (trd *TaskRunDebug) StepNeedsDebug(stepName string) bool {
-	return trd.NeedsDebugOnFailure()
+// StepNeedsDebugAfter return true if the step is configured to have a breakpoint after it's execution
+func (trd *TaskRunDebug) StepNeedsDebugAfter(stepName string) bool {
+	return slices.Contains(trd.Breakpoints.AfterBreakpoints, stepName)
+}
+
+// StepNeedsDebugBefore return true if the step is configured to have a breakpoint before it's execution
+func (trd *TaskRunDebug) StepNeedsDebugBefore(stepName string) bool {
+	return slices.Contains(trd.Breakpoints.BeforeBreakpoints, stepName)
 }
 
 // NeedsDebug return true if defined onfailure or have any before, after steps
 func (trd *TaskRunDebug) NeedsDebug() bool {
-	return trd.NeedsDebugOnFailure()
+	return trd.NeedsDebugOnFailure() || len(trd.Breakpoints.AfterBreakpoints) > 0 || len(trd.Breakpoints.BeforeBreakpoints) > 0
 }
 
 // TaskRunInputs holds the input values that this task was invoked with.

pkg/apis/pipeline/v1beta1/swagger.json

@@ -2413,6 +2413,20 @@
       "description": "TaskBreakpoints defines the breakpoint config for a particular Task",
       "type": "object",
       "properties": {
+        "afterSteps": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "default": ""
+          }
+        },
+        "beforeSteps": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "default": ""
+          }
+        },
         "onFailure": {
           "description": "if enabled, pause TaskRun on failure of a step failed step will not exit",
           "type": "string"

pkg/apis/pipeline/v1beta1/taskrun_types.go

@@ -19,6 +19,7 @@ package v1beta1
 import (
 	"context"
 	"fmt"
+	"k8s.io/utils/strings/slices"
 	"time"
 
 	"github.com/tektoncd/pipeline/pkg/apis/config"
@@ -125,6 +126,10 @@ type TaskBreakpoints struct {
 	// failed step will not exit
 	// +optional
 	OnFailure string `json:"onFailure,omitempty"`
+	// +optional
+	BeforeSteps []string `json:"beforeSteps,omitempty"`
+	// +optional
+	AfterSteps []string `json:"afterSteps,omitempty"`
 }
 
 // NeedsDebugOnFailure return true if the TaskRun is configured to debug on failure
@@ -137,12 +142,12 @@ func (trd *TaskRunDebug) NeedsDebugOnFailure() bool {
 
 // StepNeedsDebug return true if the step is configured to debug
 func (trd *TaskRunDebug) StepNeedsDebug(stepName string) bool {
-	return trd.NeedsDebugOnFailure()
+	return trd.NeedsDebugOnFailure() || slices.Contains(trd.Breakpoints.BeforeSteps, stepName) || slices.Contains(trd.Breakpoints.AfterSteps, stepName)
 }
 
 // NeedsDebug return true if defined onfailure or have any before, after steps
 func (trd *TaskRunDebug) NeedsDebug() bool {
-	return trd.NeedsDebugOnFailure()
+	return trd.NeedsDebugOnFailure() || len(trd.Breakpoints.BeforeSteps) > 0 || len(trd.Breakpoints.AfterSteps) > 0
 }
 
 var taskRunCondSet = apis.NewBatchConditionSet()

pkg/entrypoint/entrypointer.go

@@ -106,6 +106,10 @@ type Entrypointer struct {
 	Timeout *time.Duration
 	// BreakpointOnFailure helps determine if entrypoint execution needs to adapt debugging requirements
 	BreakpointOnFailure bool
+	// BreakpointAfter helps determine if entrypoint execution needs to halt after for debugging
+	BreakpointAfter bool
+	// BreakpointBefore helps determine if entrypoint execution needs to halt before for debugging
+	BreakpointBefore bool
 	// OnError defines exiting behavior of the entrypoint
 	// set it to "stopAndFail" to indicate the entrypoint to exit the taskRun if the container exits with non zero exit code
 	// set it to "continue" to indicate the entrypoint to continue executing the rest of the steps irrespective of the container exit code

pkg/pod/entrypoint.go

@@ -179,6 +179,12 @@ func orderContainers(ctx context.Context, commonExtraEntrypointArgs []string, st
 		if breakpointConfig != nil && breakpointConfig.NeedsDebugOnFailure() {
 			argsForEntrypoint = append(argsForEntrypoint, "-breakpoint_on_failure")
 		}
+		if breakpointConfig != nil && breakpointConfig.StepNeedsDebugAfter(s.Name) {
+			argsForEntrypoint = append(argsForEntrypoint, "-breakpoint_after")
+		}
+		if breakpointConfig != nil && breakpointConfig.StepNeedsDebugBefore(s.Name) {
+			argsForEntrypoint = append(argsForEntrypoint, "-breakpoint_before")
+		}
 
 		cmd, args := s.Command, s.Args
 		if len(cmd) > 0 {

pkg/pod/script.go

@@ -145,7 +145,7 @@ func convertListOfSteps(steps []v1.Step, initContainer *corev1.Container, debugC
 		}
 		containers = append(containers, *c)
 	}
-	if debugConfig != nil && debugConfig.NeedsDebugOnFailure() {
+	if debugConfig != nil && debugConfig.NeedsDebug() {
 		placeDebugScriptInContainers(containers, initContainer)
 	}
 	return containers