From ed7e1bc0643e69633e0ee1bd1a5524d65ea31ad8 Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Thu, 24 Jan 2019 12:12:40 -0600 Subject: [PATCH 1/3] Fix spacing and add links to affinity stanza from various pages --- .../docs/job-specification/affinity.html.md | 36 +++++++++++++++++-- .../docs/job-specification/group.html.md | 4 +++ .../source/docs/job-specification/job.html.md | 6 ++++ .../docs/job-specification/task.html.md | 4 +++ 4 files changed, 47 insertions(+), 3 deletions(-) diff --git a/website/source/docs/job-specification/affinity.html.md b/website/source/docs/job-specification/affinity.html.md index 56f7a6c5f..8fcd08a36 100644 --- a/website/source/docs/job-specification/affinity.html.md +++ b/website/source/docs/job-specification/affinity.html.md @@ -28,8 +28,38 @@ be expressed on [attributes][interpolation] or [client metadata][client-meta]. Additionally affinities may be specified at the [job][job], [group][group], or [task][task] levels for ultimate flexibility. -Placing the same affinity at both the job level and at the group level is redundant -since affinities are applied hierarchically. The job affinities will affect +```hcl +job "docs" { + # Prefer nodes in the us-west1 datacenter + affinity { + attribute = "${node.datacenter}" + value = "us-west1" + weight = 100 + } + + group "example" { + # Prefer the "r1" rack + affinity { + operator = "${meta.rack}" + value = "r1" + weight = 50 + } + + task "server" { + # Prefer nodes where "my_custom_value" is greater than 5 + affinity { + attribute = "${meta.my_custom_value}" + operator = ">" + value = "3" + weight = 50 + } + } + } +} +``` + +Placing affinities at both the job level and at the group level is redundant +since constraints are applied hierarchically. The job constraints will affect all groups (and tasks) in the job. Nomad will use affinities when computing scores for placement. Nodes that match affinities will @@ -154,7 +184,7 @@ This example adds a preference for running on nodes which have a kernel version higher than "3.19". ```hcl -affinity{ +affinity { attribute = "${attr.kernel.version}" operator = "version" value = "> 3.19" diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index e31bd0803..ad3f2dfa6 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -35,6 +35,9 @@ job "docs" { - `constraint` ([Constraint][]: nil) - This can be provided multiple times to define additional constraints. +- `affinity` ([Affinity][]: nil) - This can be provided + multiple times to define preferred placement criteria. + - `count` `(int: 1)` - Specifies the number of the task groups that should be running under this group. This value must be non-negative. @@ -118,6 +121,7 @@ group "example" { [task]: /docs/job-specification/task.html "Nomad task Job Specification" [job]: /docs/job-specification/job.html "Nomad job Job Specification" [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" +[affinity]: /docs/job-specification/affinity.html "Nomad affinity Job Specification" [ephemeraldisk]: /docs/job-specification/ephemeral_disk.html "Nomad ephemeral_disk Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" [migrate]: /docs/job-specification/migrate.html "Nomad migrate Job Specification" diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index 695481837..a4ccb53b0 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -75,6 +75,11 @@ job "docs" { [Nomad constraint reference](/docs/job-specification/constraint.html) for more details. +- `affinity` ([Affinity][affinity]: nil) - + This can be provided multiple times to define preferred placement criteria. See the + [Nomad affinity reference](/docs/job-specification/affinity.html) for more + details. + - `datacenters` `(array: )` - A list of datacenters in the region which are eligible for task placement. This must be provided, and does not have a default. @@ -224,6 +229,7 @@ $ VAULT_TOKEN="..." nomad job run example.nomad ``` [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" +[affinity]: /docs/job-specification/affinity.html "Nomad affinity Job Specification" [group]: /docs/job-specification/group.html "Nomad group Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" [migrate]: /docs/job-specification/migrate.html "Nomad migrate Job Specification" diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md index 7b4ce28f8..e7dcf52e1 100644 --- a/website/source/docs/job-specification/task.html.md +++ b/website/source/docs/job-specification/task.html.md @@ -45,6 +45,9 @@ job "docs" { constraints on the task. This can be provided multiple times to define additional constraints. +- `affinity` ([Affinity][]: nil) - This can be provided + multiple times to define preferred placement criteria. + - `dispatch_payload` ([DispatchPayload][]: nil) - Configures the task to have access to dispatch payloads. @@ -190,6 +193,7 @@ task "server" { [artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification" [consul]: https://www.consul.io/ "Consul by HashiCorp" [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" +[affinity]: /docs/job-specification/affinity.html "Nomad affinity Job Specification" [dispatchpayload]: /docs/job-specification/dispatch_payload.html "Nomad dispatch_payload Job Specification" [env]: /docs/job-specification/env.html "Nomad env Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" From 2db052d4adbbb93ffc2c649afec7b5aea9ee6b30 Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Thu, 24 Jan 2019 14:58:26 -0600 Subject: [PATCH 2/3] improve spread docs --- .../docs/job-specification/group.html.md | 6 +++++ .../source/docs/job-specification/job.html.md | 5 ++++ .../docs/job-specification/spread.html.md | 26 +++++++++++++++++-- 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md index ad3f2dfa6..772893a27 100644 --- a/website/source/docs/job-specification/group.html.md +++ b/website/source/docs/job-specification/group.html.md @@ -38,6 +38,11 @@ job "docs" { - `affinity` ([Affinity][]: nil) - This can be provided multiple times to define preferred placement criteria. +- `spread` ([Spread][spread]: nil) - This can be provided + multiple times to define criteria for spreading allocations across a + node attribute or metadata. See the + [Nomad spread reference](/docs/job-specification/spread.html) for more details. + - `count` `(int: 1)` - Specifies the number of the task groups that should be running under this group. This value must be non-negative. @@ -121,6 +126,7 @@ group "example" { [task]: /docs/job-specification/task.html "Nomad task Job Specification" [job]: /docs/job-specification/job.html "Nomad job Job Specification" [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" +[spread]: /docs/job-specification/spread.html "Nomad spread Job Specification" [affinity]: /docs/job-specification/affinity.html "Nomad affinity Job Specification" [ephemeraldisk]: /docs/job-specification/ephemeral_disk.html "Nomad ephemeral_disk Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index a4ccb53b0..ca7a78ceb 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -80,6 +80,10 @@ job "docs" { [Nomad affinity reference](/docs/job-specification/affinity.html) for more details. +- `spread` ([Spread][spread]: nil) - This can be provided multiple times + to define criteria for spreading allocations across a node attribute or metadata. + See the [Nomad spread reference](/docs/job-specification/spread.html) for more details. + - `datacenters` `(array: )` - A list of datacenters in the region which are eligible for task placement. This must be provided, and does not have a default. @@ -230,6 +234,7 @@ $ VAULT_TOKEN="..." nomad job run example.nomad [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" [affinity]: /docs/job-specification/affinity.html "Nomad affinity Job Specification" +[spread]: /docs/job-specification/spread.html "Nomad spread Job Specification" [group]: /docs/job-specification/group.html "Nomad group Job Specification" [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" [migrate]: /docs/job-specification/migrate.html "Nomad migrate Job Specification" diff --git a/website/source/docs/job-specification/spread.html.md b/website/source/docs/job-specification/spread.html.md index f5d1cf5aa..b07633399 100644 --- a/website/source/docs/job-specification/spread.html.md +++ b/website/source/docs/job-specification/spread.html.md @@ -29,6 +29,29 @@ The operator can specify a node attribute such as datacenter, availability zone, in a physical datacenter to spread the allocations over. By default, when using spread the scheduler will attempt to place allocations equally among the available values of the given target. + +```hcl +job "docs" { + # Spread allocations over all datacenter + spread { + attribute = "${node.datacenter}" + } + + group "example" { + # Spread allocations over each rack based on desired percentage + spread { + attribute = "${node.datacenter}" + target "us-east1" { + percent = 60 + } + target "us-west1" { + percent = 40 + } + } + } +} +``` + Nodes are scored according to how closely they match the desired target percentage defined in the spread stanza. Spread scores are combined with other scoring factors such as bin packing. @@ -38,8 +61,7 @@ Spread criteria are treated as a soft preference by the Nomad scheduler. If no nodes match a given spread criteria, placement is still successful. Spread may be expressed on [attributes][interpolation] or [client metadata][client-meta]. -Additionally, spread may be specified at the [job][job], [group][group], or -[task][task] levels for ultimate flexibility. +Additionally, spread may be specified at the [job][job] and [group][group] levels for ultimate flexibility. ## `spread` Parameters From 437ccfc1a2b3fe8a816ec39e9ac6561931753ddb Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Thu, 24 Jan 2019 16:50:23 -0600 Subject: [PATCH 3/3] review comments --- website/source/docs/job-specification/affinity.html.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/source/docs/job-specification/affinity.html.md b/website/source/docs/job-specification/affinity.html.md index 8fcd08a36..11931e9f2 100644 --- a/website/source/docs/job-specification/affinity.html.md +++ b/website/source/docs/job-specification/affinity.html.md @@ -58,9 +58,9 @@ job "docs" { } ``` -Placing affinities at both the job level and at the group level is redundant -since constraints are applied hierarchically. The job constraints will affect -all groups (and tasks) in the job. +Affinities apply to task groups but may be specified within job and task stanzas as well. +Job affinities apply to all groups within the job. Task affinities apply to the whole task group +that the task is a part of. Nomad will use affinities when computing scores for placement. Nodes that match affinities will have their scores boosted. Affinity scores are combined with other scoring factors such as bin packing.