github.com/ferranbt/nomad@v0.9.3-0.20190607002617-85c449b7667c/website/source/docs/job-specification/spread.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "spread Stanza - Job Specification"
     4  sidebar_current: "docs-job-specification-spread"
     5  description: |-
     6    The "spread" stanza is used to spread placements across a certain node attributes such as datacenter.
     7    Spread may be specified at the job, group, or task levels for ultimate flexibility.
     8    More than one spread stanza may be specified with relative weights between each.
     9  ---
    10  
    11  # `spread` Stanza
    12  
    13  <table class="table table-bordered table-striped">
    14    <tr>
    15      <th width="120">Placement</th>
    16      <td>
    17        <code>job -> **spread**</code>
    18        <br>
    19        <code>job -> group -> **spread**</code>
    20        <br>
    21        <code>job -> group -> task -> **spread**</code>
    22      </td>
    23    </tr>
    24  </table>
    25  
    26  The `spread` stanza allows operators to increase the failure tolerance of their
    27  applications by specifying a node attribute that allocations should be spread
    28  over. This allows operators to spread allocations over attributes such as
    29  datacenter, availability zone, or even rack in a physical datacenter. By
    30  default, when using spread the scheduler will attempt to place allocations
    31  equally among the available values of the given target.
    32  
    33  
    34  ```hcl
    35  job "docs" {
    36    # Spread allocations over all datacenter
    37    spread {
    38      attribute = "${node.datacenter}"
    39    }
    40  
    41    group "example" {
    42      # Spread allocations over each rack based on desired percentage
    43        spread {
    44          attribute = "${meta.rack}"
    45          target "r1" {
    46            percent = 60
    47          }
    48          target "r2" {
    49            percent = 40
    50          }
    51        }
    52    }
    53  }
    54  ```
    55  
    56  Nodes are scored according to how closely they match the desired target percentage defined in the
    57  spread stanza. Spread scores are combined with other scoring factors such as bin packing.
    58  
    59  A job or task group can have more than one spread criteria, with weights to express relative preference.
    60  
    61  Spread criteria are treated as a soft preference by the Nomad scheduler.
    62  If no nodes match a given spread criteria, placement is still successful.
    63  
    64  Spread may be expressed on [attributes][interpolation] or [client metadata][client-meta].
    65  Additionally, spread may be specified at the [job][job] and [group][group] levels for ultimate flexibility.
    66  
    67  
    68  ## `spread` Parameters
    69  
    70  - `attribute` `(string: "")` - Specifies the name or reference of the attribute
    71    to use. This can be any of the [Nomad interpolated
    72    values](/docs/runtime/interpolation.html#interpreted_node_vars).
    73  
    74  - `target` <code>([target](#target-parameters): <required>)</code> - Specifies one or more target
    75     percentages for each value of the `attribute` in the spread stanza. If this is omitted,
    76     Nomad will spread allocations evenly across all values of the attribute.
    77  
    78  - `weight` `(integer:0)` - Specifies a weight for the spread stanza. The weight is used
    79    during scoring and must be an integer between 0 to 100. Weights can be used
    80    when there is more than one spread or affinity stanza to express relative preference across them.
    81  
    82  ## `target` Parameters
    83  
    84  - `value` `(string:"")` - Specifies a target value of the attribute from a `spread` stanza.
    85  
    86  - `percent` `(integer:0)` - Specifies the percentage associated with the target value.
    87  
    88  ## `spread` Examples
    89  
    90  The following examples show different ways to use the `spread` stanza.
    91  
    92  ### Even Spread Across Data Center
    93  
    94  This example shows a spread stanza across the node's `datacenter` attribute. If we have
    95  two datacenters `us-east1` and `us-west1`, and a task group of `count = 10`,
    96  Nomad will attempt to place 5 allocations in each datacenter.
    97  
    98  ```hcl
    99  spread {
   100    attribute = "${node.datacenter}"
   101    weight    = 100
   102  }
   103  ```
   104  
   105  ### Spread With Target Percentages
   106  
   107  This example shows a spread stanza that specifies one target percentage. If we
   108  have three datacenters `us-east1`, `us-east2`, and `us-west1`, and a task group
   109  of `count = 10`, Nomad will attempt to place place 5 of the allocations in "us-east1",
   110  and will spread the remaining among the other two datacenters.
   111  
   112  ```hcl
   113  spread {
   114    attribute = "${node.datacenter}"
   115    weight    = 100
   116  
   117    target "us-east1" {
   118      percent = 50
   119    }
   120  }
   121  ```
   122  
   123  This example shows a spread stanza that specifies target percentages for two
   124  different datacenters. If we have two datacenters `us-east1` and `us-west1`,
   125  and a task group of `count = 10`, Nomad will attempt to place 6 allocations
   126  in `us-east1` and 4 in `us-west1`.
   127  
   128  ```hcl
   129  spread {
   130    attribute = "${node.datacenter}"
   131    weight    = 100
   132  
   133    target "us-east1" {
   134      percent = 60
   135    }
   136  
   137    target "us-west1" {
   138        percent = 40
   139    }
   140  }
   141  ```
   142  
   143  ### Spread Across Multiple Attributes
   144  
   145  This example shows spread stanzas with multiple attributes. Consider a Nomad cluster
   146  where there are two datacenters `us-east1` and `us-west1`, and each datacenter has nodes
   147  with `${meta.rack}` being `r1` or `r2`. With the following spread stanza used on a job with `count=12`, Nomad
   148  will attempt to place 6 allocations in each datacenter. Within a datacenter, Nomad will
   149  attempt to place 3 allocations in nodes on rack `r1`, and 3 allocations in nodes on rack `r2`.
   150  
   151  ```hcl
   152  spread {
   153    attribute = "${node.datacenter}"
   154    weight    = 50
   155  }
   156  spread {
   157    attribute = "${meta.rack}"
   158    weight    = 50
   159  }
   160  ```
   161  
   162  [job]: /docs/job-specification/job.html "Nomad job Job Specification"
   163  [group]: /docs/job-specification/group.html "Nomad group Job Specification"
   164  [client-meta]: /docs/configuration/client.html#meta "Nomad meta Job Specification"
   165  [task]: /docs/job-specification/task.html "Nomad task Job Specification"
   166  [interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
   167  [node-variables]: /docs/runtime/interpolation.html#node-variables- "Nomad interpolation-Node variables"
   168  [constraint]: /docs/job-specification/constraint.html "Nomad Constraint job Specification"