mirror of
https://github.com/ansible/awx.git
synced 2026-01-09 15:02:07 -03:30
de86b93690
* update to Python 3.12 * remove use of utcnow * switch to timezone.utc datetime.UTC is an alias of datetime.timezone.utc. if we're doing the double import for datetime it's more straightforward to just import timezone as well and get it directly * debug python env version issue * change python version * pin to SHA and remove debug portion
160 lines
6.2 KiB
Markdown
160 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 `now(datetime.UTC)` (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 `now(datetime.UTC)`. 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
|