Merge pull request #5238 from hashicorp/b-spread-docs-fixes

Documentation fixes for affinity and spread

website/source/docs/job-specification/affinity.html.md

@@ -28,9 +28,39 @@ 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
-all groups (and tasks) in the job.
+```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
+      }
+    }
+  }
+}
+```
+
+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.
@@ -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"

website/source/docs/job-specification/group.html.md

@@ -35,6 +35,14 @@ job "docs" {
 - `constraint` <code>([Constraint][]: nil)</code> -
   This can be provided multiple times to define additional constraints.
 
+- `affinity` <code>([Affinity][]: nil)</code> - This can be provided
+    multiple times to define preferred placement criteria.
+
+- `spread` <code>([Spread][spread]: nil)</code> - 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.
 
@@ -118,6 +126,8 @@ 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"
 [migrate]: /docs/job-specification/migrate.html "Nomad migrate Job Specification"

website/source/docs/job-specification/job.html.md

@@ -75,6 +75,15 @@ job "docs" {
   [Nomad constraint reference](/docs/job-specification/constraint.html) for more
   details.
 
+- `affinity` <code>([Affinity][affinity]: nil)</code> -
+    This can be provided multiple times to define preferred placement criteria. See the
+    [Nomad affinity reference](/docs/job-specification/affinity.html) for more
+    details.
+
+- `spread` <code>([Spread][spread]: nil)</code> - 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<string>: <required>)` - 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 +233,8 @@ $ 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"

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

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` <code>([Affinity][]: nil)</code> - This can be provided
+  multiple times to define preferred placement criteria.
+
 - `dispatch_payload` <code>([DispatchPayload][]: nil)</code> - 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"