switch from "unpause triggers" to "skip immediately" for clarity

Signed-off-by: Tiger Kaovilai <[email protected]>

design/schedule-skip-immediately-config_design.md

@@ -0,0 +1,119 @@
+# Schedule Skip Immediately Config Design
+## Abstract
+When unpausing schedule, a backup could be due immediately.
+New Schedules also create new backup immediately.
+
+This design allows user to *skip **immediately due** backup run upon unpausing or schedule creation*.
+
+## Background
+Currently, the default behavior of schedule when `.Status.LastBackup` is nil or is due immediately after unpausing, a backup will be created. This may not be a desired by all users (https://github.com/vmware-tanzu/velero/issues/6517)
+
+User want ability to skip the first immediately due backup when schedule is unpaused and or created.
+
+## Goals
+- Add an option so user can when unpausing (when immediately due) or creating new schedule, to not create a backup immediately.
+
+## Non Goals
+- Changing the default behavior
+
+## High-Level Design
+Add a new field with to the schedule spec and as a new cli flags for install, server, schedule commands; allowing user to skip immediately due backup when unpausing.
+
+If CLI flag is specified during schedule unpause, velero will update the schedule spec accordingly and override prior spec for `skipImmediately``.
+
+## Detailed Design
+### CLI Changes
+`velero schedule unpause` will now take an optional bool flag `--skip-immediately` to allow user to override the behavior configured previously in the schedule spec.
+
+`velero schedule unpause schedule-1 --skip-immediately=false` will unpause the schedule but not skip the backup if due immediately from `schedule.status.lastBackup` timestamp. Backup will be run at the next cron schedule.
+
+`velero schedule unpause schedule-1 --skip-immediately=true` will unpause the schedule and skip the backup if due immediately from `schedule.status.lastBackup` timestamp. Backup will also be run at the next cron schedule.
+
+`velero schedule unpause schedule-1` will check `.spec.SkipImmediately` in the schedule to determine behavior. This field will default to false to maintain prior behavior.
+
+`velero server` will add a new flag `--skip-immediately` to configure default value to patch new schedules created without the field. This flag will default to false to maintain prior behavior if not set.
+
+### API Changes
+`pkg/apis/velero/v1/schedule_types.go`
+```diff
+// ScheduleSpec defines the specification for a Velero schedule
+type ScheduleSpec struct {
+	// Template is the definition of the Backup to be run
+	// on the provided schedule
+	Template BackupSpec `json:"template"`
+
+	// Schedule is a Cron expression defining when to run
+	// the Backup.
+	Schedule string `json:"schedule"`
+
+	// UseOwnerReferencesBackup specifies whether to use
+	// OwnerReferences on backups created by this Schedule.
+	// +optional
+	// +nullable
+	UseOwnerReferencesInBackup *bool `json:"useOwnerReferencesInBackup,omitempty"`
+
+	// Paused specifies whether the schedule is paused or not
+	// +optional
+	Paused bool `json:"paused,omitempty"`
+
++	// SkipImmediately specifies whether to skip backup if schedule is due immediately from `schedule.status.lastBackup` timestamp when schedule is unpaused or if schedule is new.
++	// If true, backup will be skipped immediately when schedule is unpaused if it is due based on .Status.LastBackupTimestamp or schedule is new, and will run at next schedule time.
++	// If false, backup will not be skipped immediately when schedule is unpaused, but will run at next schedule time.
++	// If empty, will follow server configuration (default: false). 
++	// +optional
++	SkipImmediately *bool `json:"skipImmediately,omitempty"`
+}
+```
+
+`LastUnpaused` will be added to `ScheduleStatus` struct to track the last time a schedule was unpaused to support configurable unpause behavior.
+```diff
+// ScheduleStatus captures the current state of a Velero schedule
+type ScheduleStatus struct {
+	// Phase is the current phase of the Schedule
+	// +optional
+	Phase SchedulePhase `json:"phase,omitempty"`
+
+	// LastBackup is the last time a Backup was run for this
+	// Schedule schedule
+	// +optional
+	// +nullable
+	LastBackup *metav1.Time `json:"lastBackup,omitempty"`
+
++	// LastUnpaused is the last time a Schedule was unpaused
++	// +optional
++	// +nullable
++	LastUnpaused *metav1.Time `json:"lastUnpaused,omitempty"`
+
+	// ValidationErrors is a slice of all validation errors (if
+	// applicable)
+	// +optional
+	ValidationErrors []string `json:"validationErrors,omitempty"`
+}
+```
+
+`LastUnpaused` will be set to the current time when a schedule is unpaused. When a schedule is paused, `LastUnpaused` will be set to nil.
+
+When schedule is unpaused, and `schedule.status.lastBackup` is not nil, if `.spec.SkipImmediately` is true, a backup will not be created if the schedule is due immediately from lastBackup timestamp. Backup will be run at the next cron schedule.
+
+When schedule is unpaused with `schedule.status.lastBackup` set to nil or schedule is newly created, normally a backup will be created immediately. If `.spec.SkipImmediately` is true, a backup will not be created. Backup will be run at the next cron schedule.
+
+When schedule is created, if `.spec.SkipImmediately` is true, a backup will not be created. Backup will run at the next cron schedule.
+
+## Alternatives Considered
+
+N/A
+
+
+## Security Considerations
+None
+
+## Compatibility
+Upon upgrade, the new field will be added to the schedule spec automatically and will default to the prior behavior of running a backup when schedule is unpaused if it is due based on .Status.LastBackup or schedule is new.
+
+Since this is a new field, it will be ignored by older versions of velero.
+
+## Implementation
+TBD
+
+## Open Issues
+N/A