mirror of
https://github.com/ansible/awx.git
synced 2026-01-11 10:00:01 -03:30
c67f50831b
* Added schedule_rruleset lookup plugin for awx.awx * Added DB migration for rrule size * Updated schedule docs * The schedule API endpoint will now return an array of errors on rule validation to try and inform the user of all errors instead of just the first
166 lines
6.2 KiB
Markdown
166 lines
6.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 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 occurences.
|
|
|
|
|
|
## 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
|
|
|
|
|