diff --git a/website/source/api/allocations.html.md b/website/source/api/allocations.html.md index 46c7b9408..06f3f42f2 100644 --- a/website/source/api/allocations.html.md +++ b/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", diff --git a/website/source/api/jobs.html.md b/website/source/api/jobs.html.md index f699a434f..d4d16ac6e 100644 --- a/website/source/api/jobs.html.md +++ b/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, diff --git a/website/source/api/json-jobs.html.md b/website/source/api/json-jobs.html.md index 208ae670f..c2d8a66e7 100644 --- a/website/source/api/json-jobs.html.md +++ b/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" diff --git a/website/source/docs/job-specification/spread.html.md b/website/source/docs/job-specification/spread.html.md new file mode 100644 index 000000000..f5d1cf5aa --- /dev/null +++ b/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 + + + + + + +
Placement + job -> **spread** +
+ job -> group -> **spread** +
+ job -> group -> task -> **spread** +
+ +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` ([target](#target-parameters): ) - 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" \ No newline at end of file diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 5d661dae5..64a35cd2f 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -378,6 +378,9 @@ > service + > + spread + > task