Debugging Guide

kubectl edit configmap feature-flags -n tekton-pipelines

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-api-fields: "alpha"

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: debug-on-failure-
spec:
  debug:
    breakpoints:
      - onFailure
  taskSpec:
    steps:
      - name: failing-step
        image: alpine
        script: |
          echo "This step will fail"
          exit 1
      - name: next-step
        image: alpine
        script: |
          echo "This step won't execute due to failure"

# Get the pod name
kubectl get taskruns
kubectl get pods | grep <taskrun-name>

# Get logs to see breakpoint message
kubectl logs <pod-name> -c step-failing-step

This step will fail
Breakpoint on failure hit. Container will not exit.
Use the following commands to continue or fail:
  Continue: /tekton/debug/scripts/debug-continue
  Fail: /tekton/debug/scripts/debug-fail-continue

# Inside the container
cd /workspace

# Fix the issue
echo "data" > required-file.txt

# Mark as successful and continue
/tekton/debug/scripts/debug-continue

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: debug-before-step-
spec:
  debug:
    breakpoints:
      - beforeStep: critical-step
  taskSpec:
    steps:
      - name: setup
        image: alpine
        script: |
          echo "Setup complete"
      - name: critical-step
        image: alpine
        script: |
          echo "Running critical step"
          cat /workspace/important-file.txt
      - name: cleanup
        image: alpine
        script: |
          echo "Cleanup"

kubectl logs <pod-name> -c step-critical-step

debug before step breakpoint has taken effect, waiting for user's decision:
1) continue, use cmd: /tekton/debug/scripts/debug-beforestep-continue
2) fail-continue, use cmd: /tekton/debug/scripts/debug-beforestep-fail-continue

# For step index 0
ls -la /tekton/debug/info/0

# For step index 1  
ls -la /tekton/debug/info/1

# List TaskRuns
kubectl get taskruns

# Get detailed status
kubectl describe taskrun <taskrun-name>

# Watch TaskRun status
kubectl get taskrun <taskrun-name> -w

# Get pod name from TaskRun
kubectl get taskrun <taskrun-name> -o jsonpath='{.status.podName}'

# View logs for all containers
kubectl logs <pod-name> --all-containers

# View logs for specific step
kubectl logs <pod-name> -c step-<step-name>

# Follow logs in real-time
kubectl logs <pod-name> -c step-<step-name> -f

# Install tkn CLI
# https://github.com/tektoncd/cli

# View TaskRun logs
tkn taskrun logs <taskrun-name>

# Follow logs
tkn taskrun logs <taskrun-name> -f

# View TaskRun description
tkn taskrun describe <taskrun-name>

steps:
  - name: debug-environment
    image: alpine
    script: |
      echo "=== Environment Debug ==="
      echo "Working directory: $(pwd)"
      echo "User: $(id)"
      echo "Workspace path: $(workspaces.source.path)"
      echo "Workspace bound: $(workspaces.source.bound)"
      echo "Parameters:"
      echo "  app-name: $(params.app-name)"
      echo "  version: $(params.version)"
      echo "Disk usage:"
      df -h
      echo "Environment variables:"
      env | sort
  - name: actual-work
    image: builder-image
    script: |
      # Main work here

finally:
  - name: collect-logs
    when:
      - input: $(tasks.build.status)
        operator: in
        values: ["Failed"]
    taskSpec:
      steps:
        - name: save-logs
          image: alpine
          script: |
            # Collect and save debug information
            kubectl logs <pod-name> --all-containers > /workspace/logs.txt

steps:
  - name: validate-prerequisites
    image: alpine
    script: |
      # This step verifies:
      # 1. Source code is checked out
      # 2. Required config files exist
      # 3. Dependencies are available
      
      if [ ! -f "$(workspaces.source.path)/package.json" ]; then
        echo "ERROR: package.json not found"
        echo "Expected: Source workspace should contain Node.js project"
        exit 1
      fi
      
      echo "Prerequisites validated successfully"