diff --git a/website/pages/docs/job-specification/periodic.mdx b/website/pages/docs/job-specification/periodic.mdx index dd9a20e4e..10a7c876d 100644 --- a/website/pages/docs/job-specification/periodic.mdx +++ b/website/pages/docs/job-specification/periodic.mdx @@ -44,8 +44,9 @@ consistent evaluation when Nomad spans multiple time zones. 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. This is useful when wanting to account for day light - savings in various time zones. The time zone must be parsable by Golang's + 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 @@ -74,15 +75,18 @@ periodic { } ``` -## Periodic Jobs and Daylight Saving Time +## Daylight Saving Time -Though Nomad supports configuring time_zone, we strongly recommend that periodic -jobs are specified with respect to UTC time_zone. +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:* -Daylight saving changes may cause jobs to run in times unexpected to operator: A -2.30am nightly job with `America/New_York` time zone will not run on the day -daylight saving time start; a 1.30am nightly job will run twice on the day -daylight saving time ends. +- 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/gorhill/cronexpr#implementation 'List of cron expressions' +[dst]: #daylight-saving-time diff --git a/website/pages/docs/upgrade/upgrade-specific.mdx b/website/pages/docs/upgrade/upgrade-specific.mdx index b400378b3..7d69b9cc2 100644 --- a/website/pages/docs/upgrade/upgrade-specific.mdx +++ b/website/pages/docs/upgrade/upgrade-specific.mdx @@ -34,13 +34,14 @@ affected. ### Periodic Jobs and Daylight Saving Time Nomad 0.11.2 fixed a long outstanding bug affecting periodic jobs that are -scheduled to run during daylight saving transition time. +scheduled to run during Daylight Saving Time transitions. -Nomad 0.11.2 provides a more defined behvior: nomad evaluates the cron -expression with respect to specified time zone during transition. A 2.30am +Nomad 0.11.2 provides a more defined behavior: Nomad evaluates the cron +expression with respect to specified time zone during transition. A 2:30am nightly job with `America/New_York` time zone will not run on the day daylight -saving time start; similarly, a 1.30am nightly job will run twice on the day -daylight saving time ends. +saving time start; similarly, a 1:30am nightly job will run twice on the day +daylight saving time ends. See the [Daylight Saving Time][dst] documentation +for details. ## Nomad 0.11.0 @@ -496,6 +497,7 @@ deleted and then Nomad 0.3.0 can be launched. [dangling-containers]: /docs/drivers/docker#dangling-containers [drain-api]: /api-docs/nodes#drain-node [drain-cli]: /docs/commands/node/drain +[dst]: /docs/job-specification/periodic#daylight-saving-time [gh-6787]: https://github.com/hashicorp/nomad/issues/6787 [hcl2]: https://github.com/hashicorp/hcl2 [limits]: /docs/configuration#limits