github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/periodic.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: periodic Stanza - Job Specification
     4  description: |-
     5    The "periodic" stanza allows a job to run at fixed times, dates, or intervals.
     6    The easiest way to think about the periodic scheduler is "Nomad cron" or
     7    "distributed cron".
     8  ---
     9  
    10  # `periodic` Stanza
    11  
    12  <Placement groups={['job', 'periodic']} />
    13  
    14  The `periodic` stanza allows a job to run at fixed times, dates, or intervals.
    15  The easiest way to think about the periodic scheduler is "Nomad cron" or
    16  "distributed cron".
    17  
    18  ```hcl
    19  job "docs" {
    20    periodic {
    21      cron             = "*/15 * * * * *"
    22      prohibit_overlap = true
    23    }
    24  }
    25  ```
    26  
    27  The periodic expression by default evaluates in the **UTC timezone** to ensure
    28  consistent evaluation when Nomad spans multiple time zones.
    29  
    30  ## `periodic` Requirements
    31  
    32  - The job's [scheduler type][batch-type] must be `batch` or `sysbatch`.
    33  - 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.
    34  
    35  ## `periodic` Parameters
    36  
    37  - `cron` `(string: <required>)` - Specifies a cron expression configuring the
    38    interval to launch the job. In addition to [cron-specific formats][cron], this
    39    option also includes predefined expressions such as `@daily` or `@weekly`.
    40  
    41  - `prohibit_overlap` `(bool: false)` - Specifies if this job should wait until
    42    previous instances of this job have completed. This only applies to this job;
    43    it does not prevent other periodic jobs from running at the same time.
    44  
    45  - `time_zone` `(string: "UTC")` - Specifies the time zone to evaluate the next
    46    launch interval against. [Daylight Saving Time][dst] affects scheduling, so
    47    please ensure the [behavior below][dst] meets your needs. The time zone must
    48    be parsable by Golang's
    49    [LoadLocation](https://golang.org/pkg/time/#LoadLocation).
    50  
    51  - `enabled` `(bool: true)` - Specifies if this job should run. This not only
    52    prevents this job from running on the `cron` schedule but prevents force
    53    launches.
    54  
    55  ## `periodic` Examples
    56  
    57  The following examples only show the `periodic` stanzas. Remember that the
    58  `periodic` stanza is only valid in the placements listed above.
    59  
    60  ### Run Daily
    61  
    62  This example shows running a periodic job daily:
    63  
    64  ```hcl
    65  periodic {
    66    cron = "@daily"
    67  }
    68  ```
    69  
    70  ### Set Time Zone
    71  
    72  This example shows setting a time zone for the periodic job to evaluate in:
    73  
    74  ```hcl
    75  periodic {
    76    cron      = "*/15 * * * * *"
    77    time_zone = "America/New_York"
    78  }
    79  ```
    80  
    81  ## Daylight Saving Time
    82  
    83  Though Nomad supports configuring `time_zone`, we strongly recommend that periodic
    84  jobs are specified with respect to UTC `time_zone`. Only customize `time_zone`
    85  when the following daylight saving time behavior is _desired:_
    86  
    87  - When leaping forward, periodic jobs scheduled for the skipped hour (eg 2:30am
    88    in `America/New_York`) will be _skipped_ for that day (eg March 10th).
    89  
    90  - When falling back, periodic jobs scheduled for the duplicated hour (eg 1:30am
    91    in `America/New_York`) will be _run twice_ for that day (eg November 3rd).
    92  
    93  See the [multiregion] documentation for additional considerations when
    94  configuring time zones for periodic jobs.
    95  
    96  [batch-type]: /docs/job-specification/job#type 'Batch scheduler type'
    97  [cron]: https://github.com/hashicorp/cronexpr#implementation 'List of cron expressions'
    98  [dst]: #daylight-saving-time
    99  [multiregion]: /docs/job-specification/multiregion#periodic-time-zones