open-nomad/website/pages/docs/job-specification/periodic.mdx

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