»periodic Stanza

Placementjob -> periodic

The periodic stanza allows a job to run at fixed times, dates, or intervals. The easiest way to think about the periodic scheduler is "Nomad cron" or "distributed cron".

job "docs" {
  periodic {
    cron             = "*/15 * * * * *"
    prohibit_overlap = true
  }
}

The periodic expression by default evaluates in the UTC timezone to ensure consistent evaluation when Nomad spans multiple time zones.

»periodic Requirements

  • The job's scheduler type must be batch.
  • A job can not be updated to be periodically. Thus, to transition an existing job to be periodic, you must first run nomad stop -purge «job name». This is expected behavior and is to ensure that this change has been intentionally made by an operator.

»periodic Parameters

  • cron (string: <required>) - Specifies a cron expression configuring the interval to launch the job. In addition to cron-specific formats, this option also includes predefined expressions such as @daily or @weekly.

  • prohibit_overlap (bool: false) - Specifies if this job should wait until previous instances of this job have completed. This only applies to this job; it does not prevent other periodic jobs from running at the same time.

  • time_zone (string: "UTC") - Specifies the time zone to evaluate the next launch interval against. Daylight Saving Time affects scheduling, so please ensure the behavior below meets your needs. The time zone must be parsable by Golang's LoadLocation.

»periodic Examples

The following examples only show the periodic stanzas. Remember that the periodic stanza is only valid in the placements listed above.

»Run Daily

This example shows running a periodic job daily:

periodic {
  cron = "@daily"
}

»Set Time Zone

This example shows setting a time zone for the periodic job to evaluate in:

periodic {
  cron      = "*/15 * * * * *"
  time_zone = "America/New_York"
}

»Daylight Saving Time

Though Nomad supports configuring time_zone, we strongly recommend that periodic jobs are specified with respect to UTC time_zone. Only customize time_zone when the following daylight saving time behavior is desired:

  • When leaping forward, periodic jobs scheduled for the skipped hour (eg 2:30am in America/New_York) will be skipped for that day (eg March 10th).

  • When falling back, periodic jobs scheduled for the duplicated hour (eg 1:30am in America/New_York) will be run twice for that day (eg November 3rd).