Merge pull request #14664 from hashicorp/docs-multiregion-dispatch

multiregion: Added a section for multiregion parameterized job dispatch

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

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` <code>([Strategy](#strategy-parameters): nil)</code> - 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

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

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