From 76909e8b0f4ed07568a6e1e6ddab0c72cc45a249 Mon Sep 17 00:00:00 2001 From: Derek Strickland Date: Thu, 22 Sep 2022 14:49:45 -0400 Subject: [PATCH 1/6] multiregion: Added a section for multiregion parameterized job dispatch --- .../content/docs/job-specification/multiregion.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index 0d7d6076c..a34697c36 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -67,6 +67,16 @@ 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`. +## Multiregion Parameterized Job Dispatch + +While a [parameterized job] can be deployed to multiple [federated regions] +like any other job, a parameterized job operates much like a function +definition that takes variable input. Operator's are expected to invoke +the job by invoking [`job dispatch`] from the CLI or the [HTTP API]. +Job dispatching is region specific. Operators are required to dispatch +the job for each target region and provide the appropriate dispatch options +for that region. + ## `multiregion` Parameters - `strategy` ([Strategy](#strategy-parameters): nil) - Specifies @@ -264,3 +274,6 @@ 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 From a001abdcdb6a57ea046d5df02e52d004f61e8802 Mon Sep 17 00:00:00 2001 From: Derek Strickland <1111455+DerekStrickland@users.noreply.github.com> Date: Thu, 22 Sep 2022 14:56:21 -0400 Subject: [PATCH 2/6] Update multiregion.mdx --- .../content/docs/job-specification/multiregion.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index a34697c36..b2dbb352d 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -69,12 +69,11 @@ final region will unblock the regions to mark them as `successful`. ## Multiregion Parameterized Job Dispatch -While a [parameterized job] can be deployed to multiple [federated regions] -like any other job, a parameterized job operates much like a function -definition that takes variable input. Operator's are expected to invoke -the job by invoking [`job dispatch`] from the CLI or the [HTTP API]. -Job dispatching is region specific. Operators are required to dispatch -the job for each target region and provide the appropriate dispatch options +Job dispatching is region specific. While a [parameterized job] can be +deployed to 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. ## `multiregion` Parameters From 6ac87c396fc2a49b34a1379697515869d8164871 Mon Sep 17 00:00:00 2001 From: Derek Strickland <1111455+DerekStrickland@users.noreply.github.com> Date: Wed, 28 Sep 2022 07:19:54 -0400 Subject: [PATCH 3/6] Update website/content/docs/job-specification/multiregion.mdx Co-authored-by: Luiz Aoqui --- website/content/docs/job-specification/multiregion.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index b2dbb352d..7a7942c6c 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -275,4 +275,4 @@ group "worker" { [`nomad deployment unblock`]: /docs/commands/deployment/unblock [parameterized job]: /docs/job-specification/parameterized [`job dispatch`]: /docs/commands/job/dispatch -[HTTP API]: /api-docs/jobs +[HTTP API]: /api-docs/jobs#dispatch-job From 998f662ecd6c0e0f9c2b9f74edfdef864869091c Mon Sep 17 00:00:00 2001 From: Derek Strickland <1111455+DerekStrickland@users.noreply.github.com> Date: Wed, 28 Sep 2022 07:20:11 -0400 Subject: [PATCH 4/6] Update website/content/docs/job-specification/multiregion.mdx Co-authored-by: Luiz Aoqui --- website/content/docs/job-specification/multiregion.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index 7a7942c6c..a6bbb1ef7 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -70,7 +70,7 @@ final region will unblock the regions to mark them as `successful`. ## Multiregion Parameterized Job Dispatch Job dispatching is region specific. While a [parameterized job] can be -deployed to multiple [federated regions] like any other job, a parameterized +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 From 2c1df34fee197372144b3191c9464b3459719350 Mon Sep 17 00:00:00 2001 From: Derek Strickland Date: Wed, 28 Sep 2022 08:18:56 -0400 Subject: [PATCH 5/6] Apply suggestions from code review --- .../content/docs/job-specification/multiregion.mdx | 11 ++++++++++- .../content/docs/job-specification/parameterized.mdx | 4 ++++ website/content/docs/job-specification/periodic.mdx | 4 ++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/website/content/docs/job-specification/multiregion.mdx b/website/content/docs/job-specification/multiregion.mdx index a6bbb1ef7..fc41a84f9 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -67,7 +67,7 @@ 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`. -## Multiregion Parameterized Job Dispatch +## Parameterized Job Dispatch Job dispatching is region specific. While a [parameterized job] can be registered in multiple [federated regions] like any other job, a parameterized @@ -76,6 +76,14 @@ 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 Job 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 periodc configuration specifies that 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 @@ -276,3 +284,4 @@ group "worker" { [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 From 3c63967107dd8608c2e153fc3ae86ed145a03958 Mon Sep 17 00:00:00 2001 From: Derek Strickland Date: Wed, 28 Sep 2022 08:30:22 -0400 Subject: [PATCH 6/6] link from dispatch command --- website/content/docs/commands/job/dispatch.mdx | 4 ++++ website/content/docs/job-specification/multiregion.mdx | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) 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 fc41a84f9..71f80e5bb 100644 --- a/website/content/docs/job-specification/multiregion.mdx +++ b/website/content/docs/job-specification/multiregion.mdx @@ -67,7 +67,7 @@ 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 Job Dispatch +## Parameterized Dispatch Job dispatching is region specific. While a [parameterized job] can be registered in multiple [federated regions] like any other job, a parameterized @@ -76,11 +76,11 @@ 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 Job Time Zones +## 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 periodc configuration specifies that the job should run every +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.