github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/spread.mdx (about)

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