Merge pull request #5144 from hashicorp/f-spread-docs

Docs for spread stanza

website/source/api/allocations.html.md

@@ -234,6 +234,7 @@ $ curl \
           "Delay": 25000000000,
           "Mode": "delay"
         },
+        "Spreads": null,
         "Tasks": [
           {
             "Name": "redis",
@@ -296,6 +297,7 @@ $ curl \
                 }
               ]
             },
+            "Spreads": null,
             "DispatchPayload": null,
             "Meta": null,
             "KillTimeout": 5000000000,
@@ -322,6 +324,7 @@ $ curl \
     "Periodic": null,
     "ParameterizedJob": null,
     "Payload": null,
+    "Spreads": null,
     "Meta": null,
     "VaultToken": "",
     "Status": "pending",

website/source/api/jobs.html.md

@@ -599,6 +599,13 @@ $ curl \
           "Delay": 25000000000,
           "Mode": "delay"
         },
+        "Spreads": [
+           {
+           "Attribute": "${node.datacenter}",
+           "SpreadTarget": null,
+           "Weight": 100
+           }
+        ],
         "Tasks": [
           {
             "Name": "redis",
@@ -642,6 +649,7 @@ $ curl \
             "Templates": null,
             "Constraints": null,
             "Affinities":null,
+            "Spreads":null,
             "Resources": {
               "CPU": 500,
               "MemoryMB": 256,
@@ -695,6 +703,7 @@ $ curl \
     "Payload": null,
     "Meta": null,
     "VaultToken": "",
+    "Spreads": null,
     "Status": "pending",
     "StatusDescription": "",
     "Stable": false,

website/source/api/json-jobs.html.md

@@ -161,6 +161,9 @@ The `Job` object supports the following keys:
 - `Affinities` - A list to define placement preferences on nodes where a job can be
   run. See the affinity reference for more details.
 
+- `Spread` - A list to define allocation spread across attributes. See the spread reference
+  for more details.
+
 - `Datacenters` - A list of datacenters in the region which are eligible
   for task placement. This must be provided, and does not have a default.
 
@@ -264,6 +267,9 @@ attributes:
 - `Affinities` - This is a list of `Affinity` objects. See the affinity
     reference for more details.
 
+- `Spreads` - This is a list of `Spread` objects. See the spread
+  reference for more details.
+
 - `Count` - Specifies the number of the task groups that should
   be running. Must be non-negative, defaults to one.
 
@@ -322,6 +328,9 @@ The `Task` object supports the following keys:
 - `Affinities` - This is a list of `Affinity` objects. See the affinity
     reference for more details.
 
+- `Spreads` - This is a list of `Spread` objects. See the spread
+  reference for more details.
+
 - `DispatchPayload` - Configures the task to have access to dispatch payloads.
   The `DispatchPayload` object supports the following attributes:
 
@@ -959,6 +968,27 @@ README][ct].
 }
 ```
 
+### Spread
+
+Spread allow operators to target specific percentages of allocations based on
+any node attribute or metadata. More details on how they work are described
+in [spread](/docs/job-specification/spread.html).
+
+The `Spread` object supports the following keys:
+
+- `Attribute` - Specifies the attribute to examine for the
+  spread. See the [table of attributes](/docs/runtime/interpolation.html#interpreted_node_vars) for examples.
+
+- `SpreadTarget` - Specifies a list of attribute values and percentages. This is an optional field, when
+  left empty Nomad will evenly spread allocations across values of the attribute.
+     - `Value` - The value of a specific target attribute, like "dc1" for `${node.datacenter}`.
+     - `Percent` - Desired percentage of allocations for this attribute value. The sum of
+       all spread target percentages must add up to 100.
+
+- `Weight` - A non zero weight, valid values are from -100 to 100. Used to express
+   relative preference when there is more than one spread or affinity.
+
+
 [ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
 [drain]: /docs/commands/node/drain.html
 [env]: /docs/runtime/environment.html "Nomad Runtime Environment"

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

@@ -0,0 +1,145 @@
+---
+layout: "docs"
+page_title: "spread Stanza - Job Specification"
+sidebar_current: "docs-job-specification-spread"
+description: |-
+  The "spread" stanza is used to spread placements across a certain node attributes such as datacenter.
+  Spread may be specified at the job, group, or task levels for ultimate flexibility.
+  More than one spread stanza may be specified with relative weights between each.
+---
+
+# `spread` Stanza
+
+<table class="table table-bordered table-striped">
+  <tr>
+    <th width="120">Placement</th>
+    <td>
+      <code>job -> **spread**</code>
+      <br>
+      <code>job -> group -> **spread**</code>
+      <br>
+      <code>job -> group -> task -> **spread**</code>
+    </td>
+  </tr>
+</table>
+
+The spread stanza allows operators to influence the placement of allocations in a task group.
+Operators can use spread to increase failure tolerance of their application.
+The operator can specify a node attribute such as datacenter, availability zone, or even rack
+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.
+
+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.
+
+A job or task group can have more than one spread criteria, with weights to express relative preference.
+
+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.
+
+
+## `spread` Parameters
+
+- `attribute` `(string: "")` - Specifies the name or reference of the attribute
+  to use. This can be any of the [Nomad interpolated
+  values](/docs/runtime/interpolation.html#interpreted_node_vars).
+
+- `target` <code>([target](#target-parameters): <required>)</code> - Specifies one or more target
+   percentages for each value of the `attribute` in the spread stanza. If this is omitted,
+   Nomad will spread allocations evenly across all values of the attribute.
+
+- `weight` `(integer:0)` - Specifies a weight for the spread stanza. The weight is used
+  during scoring and must be an integer between 0 to 100. Weights can be used
+  when there is more than one spread or affinity stanza to express relative preference across them.
+
+## `target` Parameters
+
+- `value` `(string:"")` - Specifies a target value of the attribute from a `spread` stanza.
+
+- `percent` `(integer:0)` - Specifies the percentage associated with the target value.
+
+## `spread` Examples
+
+The following examples show different ways to use the `spread` stanza.
+
+### Even Spread Across Data Center
+
+This example shows a spread stanza across the node's `datacenter` attribute. If we have
+two datacenters `us-east1` and `us-west1`, and a task group of `count = 10`,
+Nomad will attempt to place 5 allocations in each datacenter.
+
+```hcl
+spread {
+  attribute = "${node.datacenter}"
+  weight    = 100
+}
+```
+
+### Spread With Target Percentages
+
+This example shows a spread stanza that specifies one target percentage. If we
+have three datacenters `us-east1`, `us-east2` and `us-west1`, and a task group
+of `count = 10` Nomad will attempt to place place 5 of the allocations in "us-east1",
+and then spread the rest among the other two datacenters.
+
+```hcl
+spread {
+  attribute = "${node.datacenter}"
+  weight    = 100
+
+  target "us-east1" {
+    percent = 50
+  }
+}
+```
+
+This example shows a spread stanza that specifies target percentages for two
+different datacenters. If we have two datacenters `us-east1` and `us-west1`,
+and a task group of `count = 10`, Nomad will attempt to place 6 allocations
+in `us-east1` and 4 in `us-west1`.
+
+```hcl
+spread {
+  attribute = "${node.datacenter}"
+  weight    = 100
+
+  target "us-east1" {
+    percent = 60
+  }
+
+  target "us-west1" {
+      percent = 40
+  }
+}
+```
+
+### Spread Across Multiple Attributes
+
+This example shows spread stanzas with multiple attributes. Consider a Nomad cluster
+where there are two datacenters `us-east1` and `us-west1`, and each datacenter has nodes
+with `${meta.rack}` being `r1` or `r2`. For the following spread stanza used on a job with `count=12`, Nomad
+will attempt to place 6 allocations in each datacenter. Within a datacenter, Nomad will
+attempt to place 3 allocations in nodes on rack `r1`, and 3 allocations in nodes on rack `r2`.
+
+```hcl
+spread {
+  attribute = "${node.datacenter}"
+  weight    = 50
+}
+spread {
+  attribute = "${meta.rack}"
+  weight    = 50
+}
+```
+
+[job]: /docs/job-specification/job.html "Nomad job Job Specification"
+[group]: /docs/job-specification/group.html "Nomad group Job Specification"
+[client-meta]: /docs/configuration/client.html#meta "Nomad meta Job Specification"
+[task]: /docs/job-specification/task.html "Nomad task Job Specification"
+[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
+[node-variables]: /docs/runtime/interpolation.html#node-variables- "Nomad interpolation-Node variables"
+[constraint]: /docs/job-specification/constraint.html "Nomad Constraint job Specification"

website/source/layouts/docs.erb

@@ -378,6 +378,9 @@
           <li<%= sidebar_current("docs-job-specification-service")%>>
             <a href="/docs/job-specification/service.html">service</a>
           </li>
+          <li<%= sidebar_current("docs-job-specification-spread")%>>
+            <a href="/docs/job-specification/spread.html">spread</a>
+          </li>
           <li<%= sidebar_current("docs-job-specification-task")%>>
             <a href="/docs/job-specification/task.html">task</a>
           </li>