mirror of
https://github.com/ansible/awx.git
synced 2024-10-31 15:21:13 +03:00
146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
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/
|
|
|
|
[
|
|
{"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
|
|
=================
|
|
|
|
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.
|