feat(cron): minimum interval

[Joibel]

A new field in CronWorkflows minimumInterval which specifies a minimum monotonic time between workflow creations.

Motivation

This has two main uses I can think of

• allow CronWorkflows which on first glance will run once a day to do so even in a daylight saving observing timezone.
• allow "run every interval" workflows which run rapidly on first injection into a cluster and as soon as possible again if interval has passed after downtime of the controller.

This is also possible a generically useful change now that we have schedules which allow for much more complex scheduling.

Modifications

If we attempt to schedule inside minimum interval do not do so.

Verification

New e2e test

Tested both of the next DST changes forward and backward against the CronWorkflows in the documentation.

[agilgur5]

The usefulness, esp in the DST example, makes sense. However, I'm wondering if there is precedent for this in other cron implementations? Since I imagine this has been handled before

[Joibel]

I did do some fairly extensive research into alternative golang schedulers, and didn't find any. Quartz (not implemented for go) didn't seem to do it either.

We could adopt/fork a scheduler and add it. But

• implementing it either requires persistence (which is what I leverage here) or very complex algorithms in an already hard to implement interface.
• I don't think we should do this for maintenance reasons anyway.

I thought about adopting gronx as an alternative cron scheduler. The user would have a choice per workflow. It would be relatively clean to do. But doesn't solve either problem this does.

If kubernetes ever move Cronjobs from robfig/cron we'd be best placed if we were able to follow them.

[agilgur5]

Maybe a different question then, how do people currently work around this issue in existing schedulers? (other than, well, not using a TZ or time affected by DST)

[Joibel]

Apart from those, I have no evidence of anyone doing it. It's a hard thing to research outside of cron, but no solutions for cron based scheduling anyway.

[agilgur5]

A few docs/spec suggestions

[agilgur5]

We use durations in a few places already, but I learned recently that apparently it's k8s convention to not expose them in fields since they are Go specific: https://github.com/kubernetes/community/blob/fb55d44/contributors/devel/sig-architecture/api-conventions.md#units

It also aligns with the startingDeadlineSeconds that's used for CronWorkflows already (and inherits from upstream k8s)

[Joibel]

Ah, TIL. Nice to know that.

[agilgur5]

I'd prefer if we didn't change the formatting for every row. In #13292 I specifically addressed that and tried to use a formatting that wouldn't require changing every other row if only one description changed

[agilgur5]

Suggested change

	#### Skip forward
	You can use `minimumInterval` to schedule once per day, even if the time you want is in a daylight saving skip forward period where it would otherwise be scheduled twice.
	An example 02:30:00 schedule
	```yaml
	schedules:
	- 30 2 * * *
	- 0 3 * * *
	minimumInterval: 60m
	```
	The 3:00 run of the schedule will not be scheduled every day of the year except on the day when the clock leaps forward over 2:30.
	In that case the 3:00 run will run.
	#### Skip backwards (duplication)
	You can use `minimumInterval` to schedule once per day, even if the time you want is in a daylight saving skip backwards period where it would otherwise not be scheduled.
	An example 01:30:00 schedule
	```yaml
	schedule: 30 1 * * *
	minimumInterval: 120m
	```
	This will schedule at the first 01:30 on a skip backwards change.
	The second will not run because of `minimumInterval`.
	#### `minimumInterval`
	You can set a minimum interval between runs.
	For example, if you want to ensure you only run once a day during a DST leap forward:
	```yaml
	schedules:
	- 30 2 * * *
	- 0 3 * * *
	minimumInterval: 60m
	\```
	The 3:00 schedule will never run except on the day the clock leaps forward over 2:30.
	In that case, only the 3:00 schedule will run and the 2:30 will not.
	Another example, if you want to ensure you only run once a day during a DST leap backward:
	```yaml
	schedule: 30 1 * * *
	minimumInterval: 120m
	\```
	The first run will be at 01:30.
	On the day the clock leaps backward, the second will not run because of `minimumInterval`.

• I think we can simplify this a bit and combine the two sections as two examples. We can also reduce the verbal descriptions as the examples are a lot clearer than them (I found the initial descriptions to be a bit confusing and verbose. The descriptions afterward are good, though I simplified those as well)
• Use consistent language with "runs" vs. "schedule", and "leap" vs "skip"
  • "leap" has a less technical terminology and is used often for DST (and infrequently for non-DST), so I think works a bit better as specific to DST

[agilgur5]

Suggested change

	| `minimumInterval` | None | The minimum interval between executions of this workflow. Examples: `90s`, `10m`, `2h` |
	| `minimumInterval` | None | The minimum time between runs. Examples: `90s`, `10m`, `2h` |

simplify the description and consistently use "runs". Also use "time" (vs "interval") like the field description, which also indicates the units.