Add design doc for backup cancellation

Author: Joeavaikath

design/backup_cancellation.md

@@ -3,20 +3,18 @@
 
 ## Abstract
 This proposal introduces user-initiated backup cancellation functionality to Velero, allowing users to abort running backups through a new `cancel` field in the backup specification.
-The design addresses GitHub issues #9189 and #2098 by providing a mechanism to cleanly cancel async operations and prevent resource leaks when backups need to be terminated.
+The design addresses GitHub issues [#9189](https://github.com/vmware-tanzu/velero/issues/9189
+) and [#2098](https://github.com/vmware-tanzu/velero/issues/2098) by providing a mechanism to cleanly cancel async operations and prevent resource leaks when backups need to be terminated.
 
 ## Background
 Currently, Velero lacks the ability to cancel running backups, leading to several critical issues.
 When users accidentally submit broad backup jobs (e.g., forgot to narrow resource selectors), the system becomes blocked and scheduled jobs accumulate.
-Additionally, the backup deletion controller doesn't prevent running backups from being deleted, causing async operations (DataUpload, PodVolumeBackup, itemBlock processing) to continue running unaware of the backup deletion, resulting in resource contests and incomplete backup data leaks.
+Additionally, the backup deletion controller prevents running backups from being deleted.
 
-This problem is particularly acute in environments with frequent scheduled backups or large-scale backup operations that may run for extended periods.
-Users currently have no way to abort problematic backups other than restarting the Velero server, which affects all ongoing operations.
 
 ## Goals
 - Enable users to cancel running backups through a `cancel` field in the backup specification
 - Cleanly cancel all associated async operations (BackupItemAction operations, DataUploads, PodVolumeBackups)
-- Prevent resource leaks and contests when backups are deleted or cancelled
 - Provide clear backup phase transitions (InProgress → Cancelling → Cancelled)
 
 ## Non Goals
@@ -30,7 +28,7 @@ The solution introduces a new `cancel` boolean field to the backup specification
 Existing controllers (backup_controller, backup_operations_controller, backup_finalizer_controller) will check for this field and transition the backup to a `Cancelling` phase before returning early from their reconcile loops.
 
 A new dedicated backup cancellation controller will watch for backups in the `Cancelling` phase and coordinate the actual cancellation work.
-This controller will call `Cancel()` methods on all in-progress BackupItemAction operations (which automatically handle DataUpload cancellation), directly cancel PodVolumeBackups by setting their cancel flags, and finally transition the backup to `Cancelled` phase.
+This controller will call `Cancel()` methods on all in-progress BackupItemAction operations (which automatically handles DataUpload cancellation), directly cancel PodVolumeBackups by setting their cancel flags, and finally transition the backup to `Cancelled` phase.
 The design uses a 5-second ticker to prevent API overload and ensures clean separation between cancellation detection and execution.
 
 ## Detailed Design
@@ -73,6 +71,7 @@ if backup.Spec.Cancel != nil && *backup.Spec.Cancel {
     return ctrl.Result{}, nil // Skip processing for cancelling/cancelled backups
 }
 ```
+In addition, the `backup_operations_controller.go` will have a periodic check around backup progress updates, rather than running every time progress is updated to reduce API load.
 
 #### New Backup Cancellation Controller
 Create `backup_cancellation_controller.go`:
@@ -110,22 +109,15 @@ For PodVolumeBackups (which lack BackupItemAction implementations):
 2. Sets `pvb.Spec.Cancel = true` on in-progress PVBs
 3. Node-agent PodVolumeBackup controller handles actual cancellation
 
-### Timing and Frequency
-- Use 5-second ticker for cancellation controller to prevent API overload
-- Existing controllers check cancellation on every reconcile (event-driven)
-- No timeout for cancellation operations (rely on existing operation timeouts)
 
 ## Alternatives Considered
 
-### Alternative 1: Immediate Cancellation in Existing Controllers
-Instead of a dedicated cancellation controller, existing controllers could immediately cancel operations when detecting the cancel flag.
-This was rejected because it would complicate the existing controller logic and make the cancellation process less observable and debuggable.
 
-### Alternative 2: Deletion-Based Cancellation
+### Alternative 1: Deletion-Based Cancellation
 Using backup deletion as the cancellation mechanism instead of a cancel field.
 This was rejected because it doesn't allow users to preserve the backup object for inspection after cancellation, and deletion has different semantic meaning.
 
-### Alternative 3: Timeout-Based Automatic Cancellation
+### Alternative 2: Timeout-Based Automatic Cancellation
 Automatically cancelling backups after a configurable timeout.
 This was considered out of scope for the initial implementation as it addresses a different use case than user-initiated cancellation.
 
@@ -153,11 +145,6 @@ Implementation will be done incrementally in the following phases:
 
 **Phase 3**: Testing and refinement
 - Comprehensive end-to-end testing
-- Performance testing with cancellation controller ticker
+- Testing if slowdowns occur due to the frequency of checking `backup.Cancel` spec field
 - Documentation and user guide updates
 
-Target timeline: 1-2 sprints for core implementation, with additional time for testing and documentation.
-
-## Open Issues
-- **PodVolumeBackup operation mapping**: Unlike DataUploads which are created by BackupItemActions with operationIDs, PodVolumeBackups are created directly and don't have a clear mapping to backup item operations. The current approach of finding PVBs by backup UID label should work but needs validation.
-- **Partial cancellation handling**: Determining the appropriate backup phase when some operations cancel successfully while others fail to cancel requires further investigation.