From 6b4c79c90f8adaf1e058979d06dddbebdd380c0d Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Mon, 10 Dec 2018 11:54:23 -0600 Subject: [PATCH 1/3] Initial spread docs --- .../docs/job-specification/spread.html.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 website/source/docs/job-specification/spread.html.md 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..6337897af --- /dev/null +++ b/website/source/docs/job-specification/spread.html.md @@ -0,0 +1,117 @@ +--- +layout: "docs" +page_title: "spread Stanza - Job Specification" +sidebar_current: "docs-job-specification-spread" +description: |- + The "spread" stanza allows operators to configure desired target percentages for allocations according to node attributes or metadata. + 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 specify target percentages of allocations according to +specific node attributes or metadata. 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. + +Nomad will use any defined spread criteria when computing node scores for placement. +Nodes are scored acccording 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` 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 -100 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. Allocations +are placed evenly across all datacenters with this example. + +```hcl +spread { + attribute = "${node.datacenter}" + weight = 100 +} +``` + +### Spread With Target Percentages + +This example shows a spread stanza that specifies target percentages for two +different datacenters. + +```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 + +```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" + + From 7ef1669363dc5202f15663d5d60a606ef1f29609 Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Thu, 3 Jan 2019 21:59:23 -0600 Subject: [PATCH 2/3] Spread json docs --- website/source/api/allocations.html.md | 3 +++ website/source/api/jobs.html.md | 9 ++++++++ website/source/api/json-jobs.html.md | 30 ++++++++++++++++++++++++++ website/source/layouts/docs.erb | 3 +++ 4 files changed, 45 insertions(+) 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/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 From e12dd2f4d54a0405ad461051f2c54d8b2e2c2ebe Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Thu, 10 Jan 2019 15:46:03 -0600 Subject: [PATCH 3/3] Address review comments --- .../docs/job-specification/spread.html.md | 64 +++++++++++++------ 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/website/source/docs/job-specification/spread.html.md b/website/source/docs/job-specification/spread.html.md index 6337897af..f5d1cf5aa 100644 --- a/website/source/docs/job-specification/spread.html.md +++ b/website/source/docs/job-specification/spread.html.md @@ -3,7 +3,7 @@ layout: "docs" page_title: "spread Stanza - Job Specification" sidebar_current: "docs-job-specification-spread" description: |- - The "spread" stanza allows operators to configure desired target percentages for allocations according to node attributes or metadata. + 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. --- @@ -23,19 +23,24 @@ description: |- -The `spread` stanza allows operators to specify target percentages of allocations according to -specific node attributes or metadata. 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. +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. -Nomad will use any defined spread criteria when computing node scores for placement. -Nodes are scored acccording to how closely they match the desired target percentage defined in the +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 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 @@ -48,7 +53,7 @@ Spread criteria are treated as a soft preference by the Nomad scheduler. If no n 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 -100 to 100. Weights can be 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 @@ -63,8 +68,9 @@ 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. Allocations -are placed evenly across all datacenters with this example. +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 { @@ -75,16 +81,36 @@ spread { ### Spread With Target Percentages -This example shows a spread stanza that specifies target percentages for two -different datacenters. +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 } @@ -93,7 +119,11 @@ spread { ### Spread Across Multiple Attributes -This example shows spread stanzas with 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 { @@ -112,6 +142,4 @@ spread { [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" - - +[constraint]: /docs/job-specification/constraint.html "Nomad Constraint job Specification" \ No newline at end of file