mirror of
https://github.com/ansible/awx.git
synced 2026-02-25 15:06:02 -03:30
Merge pull request #1024 from ryanpetrello/fix-710-schedule-timezone
support TZID= in schedule rrules
This commit is contained in:
Ryan Petrello
GitHub
145
docs/schedules.md
Normal file
145
docs/schedules.md
Normal file
@@ -0,0 +1,145 @@
|
||||
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. The
|
||||
specific example above would run a job every day - for seven consecutive days - starting
|
||||
on January 15th, 2030 at noon (UTC).
|
||||
|
||||
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/
|
||||
|
||||
[
|
||||
"Africa/Abidjan",
|
||||
"Africa/Accra",
|
||||
"Africa/Addis_Ababa",
|
||||
...
|
||||
]
|
||||
|
||||
|
||||
UNTIL and Timezones
|
||||
===================
|
||||
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, this RRULE:
|
||||
|
||||
`DTSTART:20180601T120000Z RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000Z`
|
||||
|
||||
...will be interpretted as "Starting on June 1st, 2018 at noon UTC, repeat
|
||||
daily, ending on June 6th, 2018 at 5PM UTC".
|
||||
|
||||
This RRULE:
|
||||
|
||||
`DTSTART;TZID=America/New_York:20180601T120000 RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20180606T170000`
|
||||
|
||||
...will be interpretted as "Starting on June 1st, 2018 at noon EDT, repeat
|
||||
daily, ending on June 6th, 2018 at 5PM EDT".
|
||||
|
||||
|
||||
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
|
||||
=================
|
||||
|
||||
The following aspects of `RFC5545` are _not_ supported by awx schedules:
|
||||
|
||||
* Strings with more than a single `DTSTART:` component
|
||||
* Strings with more than a single `RRULE` component
|
||||
* The use of `FREQ=SECONDLY` in an `RRULE`
|
||||
* The use of more than a single `FREQ=BYMONTHDAY` component in an `RRULE`
|
||||
* The use of more than a single `FREQ=BYMONTHS` component in an `RRULE`
|
||||
* The use of `FREQ=BYYEARDAY` in an `RRULE`
|
||||
* The use of `FREQ=BYWEEKNO` in an `RRULE`
|
||||
* The use of `FREQ=BYWEEKNO` in an `RRULE`
|
||||
* The use of `COUNT=` in an `RRULE` with a value over 999
|
||||
|
||||
|
||||
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 occurences.
|
||||
Reference in New Issue
Block a user