diff --git a/website/content/docs/commands/job/dispatch.mdx b/website/content/docs/commands/job/dispatch.mdx index 4bf614579..9891d7c26 100644 --- a/website/content/docs/commands/job/dispatch.mdx +++ b/website/content/docs/commands/job/dispatch.mdx @@ -47,6 +47,9 @@ client connection issues or internal errors, are indicated by exit code 1. When ACLs are enabled, this command requires a token with the `dispatch-job` capability for the job's namespace. +See the [multiregion] documentation for additional considerations when +dispatching parameterized jobs. + ## General Options @include 'general_options.mdx' @@ -140,3 +143,4 @@ Job "video-encode/dispatch-1485379325-cb38d00d" already dispatched with idempote [eval status]: /docs/commands/eval/status [parameterized job]: /docs/job-specification/parameterized 'Nomad parameterized Job Specification' +[multiregion]: /docs/job-specification/multiregion#parameterized-dispatch diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index 0d7d6076c..71f80e5bb 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -67,6 +67,23 @@ a time. When each region completes its local deployment, it enters a `blocked` state where it waits until the last region has completed the deployment. The final region will unblock the regions to mark them as `successful`. +## Parameterized Dispatch + +Job dispatching is region specific. While a [parameterized job] can be +registered in multiple [federated regions] like any other job, a parameterized +job operates much like a function definition that takes variable input. +Operators are expected to invoke the job by invoking [`job dispatch`] +from the CLI or the [HTTP API] and provide the appropriate dispatch options +for that region. + +## Periodic Time Zones + +Multiregion periodic jobs share [time zone] configuration, with UTC being the +default. Operators should be mindful of this when registering multiregion jobs. +For example, a periodic configuration that specifies the job should run every +night at midnight New York time, may result in an undesirable execution time +if one of the target regions is set to Tokyo time. + ## `multiregion` Parameters - `strategy` ([Strategy](#strategy-parameters): nil) - Specifies @@ -264,3 +281,7 @@ group "worker" { [examples]: #multiregion-examples [upgrade strategies]: https://learn.hashicorp.com/collections/nomad/job-updates [`nomad deployment unblock`]: /docs/commands/deployment/unblock +[parameterized job]: /docs/job-specification/parameterized +[`job dispatch`]: /docs/commands/job/dispatch +[HTTP API]: /api-docs/jobs#dispatch-job +[time zone]: /docs/job-specification/periodic#time_zone diff --git a/website/content/docs/job-specification/parameterized.mdx b/website/content/docs/job-specification/parameterized.mdx index 94814287a..3bd458479 100644 --- a/website/content/docs/job-specification/parameterized.mdx +++ b/website/content/docs/job-specification/parameterized.mdx @@ -53,6 +53,9 @@ job "docs" { } ``` +See the [multiregion] documentation for additional considerations when +dispatching parameterized jobs. + ## `parameterized` Requirements - The job's [scheduler type][batch-type] must be `batch` or `sysbatch`. @@ -154,3 +157,4 @@ job "email-blast" { [resources]: /docs/job-specification/resources 'Nomad resources Job Specification' [interpolation]: /docs/runtime/interpolation 'Nomad Runtime Interpolation' [dispatch_payload]: /docs/job-specification/dispatch_payload 'Nomad dispatch_payload Job Specification' +[multiregion]: /docs/job-specification/multiregion#parameterized-dispatch diff --git a/website/content/docs/job-specification/periodic.mdx b/website/content/docs/job-specification/periodic.mdx index a867827f1..1d0c837e7 100644 --- a/website/content/docs/job-specification/periodic.mdx +++ b/website/content/docs/job-specification/periodic.mdx @@ -86,6 +86,10 @@ when the following daylight saving time behavior is _desired:_ - 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]: /docs/job-specification/job#type 'Batch scheduler type' [cron]: https://github.com/hashicorp/cronexpr#implementation 'List of cron expressions' [dst]: #daylight-saving-time +[multiregion]: /docs/job-specification/multiregion#periodic-time-zones