93 lines
3.1 KiB
Plaintext
93 lines
3.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: periodic Stanza - Job Specification
|
|
sidebar_title: periodic
|
|
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`.
|
|
- 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).
|
|
|
|
## `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).
|
|
|
|
[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
|