1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
## Scheduled Jobs
AWX allows jobs to run on a schedule (with optional recurrence rules) via
an `HTTP POST` to a variety of API endpoints:
HTTP POST
https://tower-host.example.org/api/v2/job_templates/N/schedules/
https://tower-host.example.org/api/v2/projects/N/schedules/
https://tower-host.example.org/api/v2/inventory_sources/N/schedules/
https://tower-host.example.org/api/v2/system_jobs/N/schedules/
https://tower-host.example.org/api/v2/workflow_job_templates/N/schedules/
{
'name': 'My Schedule Name',
'rrule': 'DTSTART:20300115T120000Z RRULE:FREQ=DAILY;INTERVAL=1;COUNT=7'
'extra_data': {}
}
...where `rrule` is a valid
[RFC5545](https://www.rfc-editor.org/rfc/rfc5545.txt) RRULE string and within AWX [RRULE Limitations](#rrule-limitations).
The specific example above would run a job every day - for seven consecutive days - starting
on January 15th, 2030 at noon (UTC).
For more examples see [RRULE Examples](#rrule-examples).
## Specifying Timezones
`DTSTART` values provided to AWX _must_ provide timezone information (they may
not be naive dates).
For UTC dates, `DTSTART` values should be denoted with the `Z` suffix:
DTSTART:20300115T120000Z
Local timezones can be specified using the `TZID=` parameter:
DTSTART;TZID=America/New_York:20300115T120000
A list of _valid_ zone identifiers (which can vary by system) can be found at:
HTTP GET /api/v2/schedules/zoneinfo/
[
{"name": "Africa/Abidjan"},
{"name": "Africa/Accra"},
{"name": "Africa/Addis_Ababa"},
...
]
## UNTIL and Timezones
`DTSTART` values provided to AWX _must_ provide timezone information (they may
not be naive dates).
Additionally, RFC5545 specifies that:
> Furthermore, if the "DTSTART" property is specified as a date with local
> time, then the UNTIL rule part MUST also be specified as a date with local
> time. If the "DTSTART" property is specified as a date with UTC time or
> a date with local time and time zone reference, then the UNTIL rule part
> MUST be specified as a date with UTC time.
Given this, `RRULE` values that specify `UNTIL` datetimes must _always_ be in UTC.
Valid:
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
Not Valid:
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000`
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000`
## Previewing Schedules
AWX provides an endpoint for previewing the future dates and times for
a specified `RRULE`. A list of the next _ten_ occurrences will be returned in
local and UTC time:
POST https://tower-host.example.org/api/v2/schedules/preview/
{
'rrule': 'DTSTART;TZID=America/New_York:20300115T120000 RRULE:FREQ=DAILY;INTERVAL=1;COUNT=7'
}
Content-Type: application/json
{
"local": [
"2030-01-15T12:00:00-05:00",
"2030-01-16T12:00:00-05:00",
"2030-01-17T12:00:00-05:00",
"2030-01-18T12:00:00-05:00",
"2030-01-19T12:00:00-05:00",
"2030-01-20T12:00:00-05:00",
"2030-01-21T12:00:00-05:00"
],
"utc": [
"2030-01-15T17:00:00Z",
"2030-01-16T17:00:00Z",
"2030-01-17T17:00:00Z",
"2030-01-18T17:00:00Z",
"2030-01-19T17:00:00Z",
"2030-01-20T17:00:00Z",
"2030-01-21T17:00:00Z"
]
}
## RRULE Limitations
AWX implements the following constraints on top of the `RFC5545` specification:
- The RRULE must start with the `DTSTART` attribute
- At least one `RRULE` entry must be in the rrule
- Strings with more than a single `DTSTART:` component are prohibited
- The use of `RDATE` or `EXDATE`is prohibited
- For any of the rules in the rrule:
- `Interval` must be included
- The use of `FREQ=SECONDLY` is prohibited
- The usage of a `BYDAY` with a prefixed number is prohibited
- The usage of both `COUNT` and `UNTIL` in the same rule is prohibited
- The use of `COUNT=` with a value over 999 is prohibited
## Implementation Details
Any time an `awx.model.Schedule` is saved with a valid `rrule` value, the
`dateutil` library is used to burst out a list of all occurrences. From here,
the following dates are saved in the database:
- `main_schedule.rrule` - the original `RRULE` string provided by the user
- `main_schedule.dtstart` - the _first_ datetime in the list of all occurrences (coerced to UTC)
- `main_schedule.dtend` - the _last_ datetime in the list of all occurrences (coerced to UTC)
- `main_schedule.next_run` - the _next_ datetime in list after `utcnow()` (coerced to UTC)
AWX makes use of [Celery Periodic Tasks
(celerybeat)](http://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html)
to run a periodic task that discovers new jobs that need to run at a regular
interval (by default, every 30 seconds). When this task starts, it queries the
database for Schedules where `Schedule.next_run` is between
`scheduler_last_runtime()` and `utcnow()`. For each of these, a new job is
launched, and `Schedule.next_run` is changed to the next chronological datetime
in the list of all occurrences.
## Complex RRULE Examples
Every day except for April 30th:
DTSTART;TZID=US/Eastern:20230428T170000 RRULE:INTERVAL=1;FREQ=DAILY EXRULE:INTERVAL=1;FREQ=DAILY;BYMONTH=4;BYMONTHDAY=30
Every 5 minutes but not on Mondays from 5-7pm:
DTSTART;TZID=America/New_York:20220418T164500 RRULE:INTERVAL=5;FREQ=MINUTELY EXRULE:FREQ=MINUTELY;INTERVAL=5;BYDAY=MO;BYHOUR=17,18
Every 15 minutes Monday to Friday from 10:01am to 6:02pm (inclusive):
DTSTART;TZID=America/New_York:20220417T100100 RRULE:INTERVAL=15;FREQ=MINUTELY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=10,11,12,13,14,15,16,17,18 EXRULE:INTERVAL=15;FREQ=MINUTELY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=18;BYMINUTE=3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,34,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59
Any Saturday whose month day is between 12 and 18:
DTSTART:20191219T130551Z RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=SA;BYMONTHDAY=12,13,14,15,16,17,18
|
