From d26d24968eceddb57c53f3e987a43e9174314fd7 Mon Sep 17 00:00:00 2001 From: Michael Smithhisler Date: Thu, 4 Dec 2025 15:39:02 -0500 Subject: [PATCH 1/3] nomad: updates disconnect block docs to clarify default lost_after and fix conflicting statements --- .../v1.11.x/content/docs/job-specification/disconnect.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx index 29c6b36ac2..a267d097d5 100644 --- a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx +++ b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx @@ -49,7 +49,7 @@ same `disconnect` block. - `lost_after` `(string: "")` - Specifies a duration during which a Nomad client will attempt to reconnect allocations after it fails to heartbeat in the [`heartbeat_grace`][] window. It defaults to "", which is equivalent to - having the disconnect block be nil. + a `lost_after` of `"0s"` where allocations will immediately be marked lost. You cannot use `lost_after` and `stop_on_client_after` in the same `disconnect` block. @@ -71,10 +71,7 @@ same `disconnect` block. disconnected. - `stop_on_client_after` `(string: "")` - Specifies a duration after which a - disconnected Nomad client will stop its allocations. Setting - `stop_on_client_after` shorter than `lost_after` and `replace = false` at the - same time is not permitted and will cause a validation error, because this - would lead to a state where no allocations can be scheduled. + disconnected Nomad client will stop its allocations. The Nomad client process must be running for this to occur. From 79fbbbcdee86051ce323dba079cfc5cd55a5bca6 Mon Sep 17 00:00:00 2001 From: Michael Smithhisler Date: Mon, 8 Dec 2025 16:08:16 -0500 Subject: [PATCH 2/3] more disconnect block updates and remove confusing links --- .../docs/job-specification/disconnect.mdx | 25 ++++++++++--------- .../docs/job-specification/migrate.mdx | 2 +- .../docs/job-specification/reschedule.mdx | 2 +- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx index a267d097d5..b6a1034c4c 100644 --- a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx +++ b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx @@ -26,7 +26,7 @@ job "docs" { group "example" { disconnect { lost_after = "6h" - replace = false + replace = true reconcile = "keep_original" } } @@ -34,7 +34,7 @@ job "docs" { group "example2" { disconnect { stop_on_client_after = "12h" - replace = false + replace = true reconcile = "keep_original" } } @@ -48,20 +48,21 @@ same `disconnect` block. - `lost_after` `(string: "")` - Specifies a duration during which a Nomad client will attempt to reconnect allocations after it fails to heartbeat in the - [`heartbeat_grace`][] window. It defaults to "", which is equivalent to - a `lost_after` of `"0s"` where allocations will immediately be marked lost. - - You cannot use `lost_after` and `stop_on_client_after` in the same - `disconnect` block. + [`heartbeat_grace`][] window. Allocations with a `lost_after` > 0s are put into + an `unknown` state until they reconnect or the `lost_after` expires. + It defaults to "", which is equivalent to a `lost_after` of `"0s"` where + allocations will immediately be marked lost. Refer to [the Lost After section][lost-after] for more details. - `replace` `(bool: true)` - Specifies if Nomad should replace the disconnected - allocation with a new one rescheduled on a different node. Nomad considers the - replacement allocation a reschedule and obeys the job's [`reschedule`][] - block. If false and the node the allocation is running on disconnects - or goes down, Nomad does not replace this allocation and reports `unknown` - until the node reconnects, or until you manually stop the allocation. + (i.e. `unknown`) allocation with a new one rescheduled on a different node. + Nomad considers the replacement allocation a reschedule and obeys the job's + [`reschedule`][] block. If false and the node the allocation is running on + disconnects or goes down, Nomad does not replace this allocation. + + Note: The `replace` field is only relevant for behavior when `lost_after` + is used and the allocation is in the `unknown` state. ```plaintext `nomad alloc stop ` diff --git a/content/nomad/v1.11.x/content/docs/job-specification/migrate.mdx b/content/nomad/v1.11.x/content/docs/job-specification/migrate.mdx index 2e9574936e..a64c4315ab 100644 --- a/content/nomad/v1.11.x/content/docs/job-specification/migrate.mdx +++ b/content/nomad/v1.11.x/content/docs/job-specification/migrate.mdx @@ -84,6 +84,6 @@ on node draining. [count]: /nomad/docs/job-specification/group#count [drain]: /nomad/commands/node/drain [deadline]: /nomad/commands/node/drain#deadline -[replaces]: /nomad/docs/job-specification/disconnect#replace +[replaces]: /nomad/docs/job-specification/disconnect [`restart`]: /nomad/docs/job-specification/restart [reschedules]: /nomad/docs/job-specification/reschedule diff --git a/content/nomad/v1.11.x/content/docs/job-specification/reschedule.mdx b/content/nomad/v1.11.x/content/docs/job-specification/reschedule.mdx index d4dfe5784d..9ae3d2f68c 100644 --- a/content/nomad/v1.11.x/content/docs/job-specification/reschedule.mdx +++ b/content/nomad/v1.11.x/content/docs/job-specification/reschedule.mdx @@ -139,5 +139,5 @@ job "docs" { [`progress_deadline`]: /nomad/docs/job-specification/update#progress_deadline [`restart`]: /nomad/docs/job-specification/restart [migrates]: /nomad/docs/job-specification/migrate -[replaces]: /nomad/docs/job-specification/disconnect#replace +[replaces]: /nomad/docs/job-specification/disconnect [reschedules]: /nomad/docs/job-specification/reschedule From 39ac539219d82c66996c70524ad2c360e7bdd71e Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 9 Dec 2025 09:31:07 -0600 Subject: [PATCH 3/3] Update content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx Co-authored-by: Tim Gross --- .../v1.11.x/content/docs/job-specification/disconnect.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx index b6a1034c4c..4ff1d7faaf 100644 --- a/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx +++ b/content/nomad/v1.11.x/content/docs/job-specification/disconnect.mdx @@ -58,8 +58,8 @@ same `disconnect` block. - `replace` `(bool: true)` - Specifies if Nomad should replace the disconnected (i.e. `unknown`) allocation with a new one rescheduled on a different node. Nomad considers the replacement allocation a reschedule and obeys the job's - [`reschedule`][] block. If false and the node the allocation is running on - disconnects or goes down, Nomad does not replace this allocation. + [`reschedule`][] block. If false, Nomad does not replace the allocation + when the node it's running on disconnects or goes down. Note: The `replace` field is only relevant for behavior when `lost_after` is used and the allocation is in the `unknown` state.