open-nomad/website/content/docs/job-specification/periodic.mdx
Ashlee M Boyer 57f8ebfa26
docs: Migrate link formats (#15779)
* Adding check-legacy-links-format workflow

* Adding test-link-rewrites workflow

* chore: updates link checker workflow hash

* Migrating links to new format

Co-authored-by: Kendall Strautman <kendallstrautman@gmail.com>
2023-01-25 09:31:14 -08:00

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]: /nomad/docs/job-specification/job#type 'Batch scheduler type'
[cron]: https://github.com/hashicorp/cronexpr#implementation 'List of cron expressions'
[dst]: #daylight-saving-time
[multiregion]: /nomad/docs/job-specification/multiregion#periodic-time-zones