awx/docs/schedules.md

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 RRULE string and within AWX 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.

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 EXDATEis 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) 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