0a80a58394
This is probably undocumented for a reason, but the `enabled` toggle in the `periodic` stanza is very useful so I figured I try adding it to the docs. The feature has been secretly avaliable since #9142 and was called out in that PR as being a dubious addition, only added to avoid regressions. The use case for disabling a periodic job in this way is to prevent it from running without modifying the schedule. Ideally Nomad would make it more clear that this was the case, and allow you to force a run of the job, but even with those rough edges I think users would benefit from knowing about this toggle.
100 lines
3.4 KiB
Plaintext
100 lines
3.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: periodic Stanza - Job Specification
|
|
description: |-
|
|
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".
|
|
---
|
|
|
|
# `periodic` Stanza
|
|
|
|
<Placement groups={['job', '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".
|
|
|
|
```hcl
|
|
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][batch-type] must be `batch` or `sysbatch`.
|
|
- 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][cron], 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][dst] affects scheduling, so
|
|
please ensure the [behavior below][dst] meets your needs. The time zone must
|
|
be parsable by Golang's
|
|
[LoadLocation](https://golang.org/pkg/time/#LoadLocation).
|
|
|
|
- `enabled` `(bool: true)` - Specifies if this job should run. This not only
|
|
prevents this job from running on the `cron` schedule but prevents force
|
|
launches.
|
|
|
|
## `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:
|
|
|
|
```hcl
|
|
periodic {
|
|
cron = "@daily"
|
|
}
|
|
```
|
|
|
|
### Set Time Zone
|
|
|
|
This example shows setting a time zone for the periodic job to evaluate in:
|
|
|
|
```hcl
|
|
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).
|
|
|
|
See the [multiregion] documentation for additional considerations when
|
|
configuring time zones for periodic jobs.
|
|
|
|
[batch-type]: /docs/job-specification/job#type 'Batch scheduler type'
|
|
[cron]: https://github.com/hashicorp/cronexpr#implementation 'List of cron expressions'
|
|
[dst]: #daylight-saving-time
|
|
[multiregion]: /docs/job-specification/multiregion#periodic-time-zones
|