nomad/website/content/docs/job-specification/periodic.mdx

---
layout: docs
page_title: periodic Block - Job Specification
description: |-
  The "periodic" block 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` Block

<Placement groups={['job', 'periodic']} />

The `periodic` block 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.

Refer to the [parameterized] documentation for how to use parameters with a periodic job.

## `periodic` Parameters

- `cron` (_deprecated_: Replaced by `crons` in 1.6.2) `(string)` - 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`. Either `cron` or `crons` must be set, but not both.

- `crons` - A list of cron expressions configuring the intervals the job is
  launched at. The job runs at the next earliest time that matches any of the
  expressions. Supports predefined expressions such as `@daily` and
  `@weekly`. Refer to [the
  documentation](https://github.com/hashicorp/cronexpr#implementation) for full
  details about the supported cron specs and the predefined expressions. Either `cron` or `crons` must be set, but not both.

- `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` blocks. Remember that the
`periodic` block 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"
}
```

### Run multiple crons

```hcl
periodic {
  crons = [
    "*/5 * * *",
    "*/7 * * *"
  ]
  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
[parameterized]: /nomad/docs/job-specification/parameterized#use-periodic-with-parameterized