github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/job-specification/spread.mdx (about)

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