OpenSearch/docs/reference/index-modules/allocation.asciidoc

[[index-modules-allocation]]
== Index Shard Allocation

This module provides per-index settings to control the allocation of shards to
nodes.

[float]
[[shard-allocation-filtering]]
=== Shard Allocation Filtering

Shard allocation filtering allows you to specify which nodes are allowed
to host the shards of a particular index.

NOTE: The per-index shard allocation filters explained below work in
conjunction with the cluster-wide allocation filters explained in
<<shards-allocation>>.

It is possible to assign arbitrary metadata attributes to each node at
startup.  For instance, nodes could be assigned a `rack` and a `group`
attribute as follows:

[source,sh]
------------------------
bin/elasticsearch --node.rack rack1 --node.size big  <1>
------------------------
<1> These attribute settings can also be specfied in the `elasticsearch.yml` config file.

These metadata attributes can be used with the
`index.routing.allocation.*` settings to allocate an index to a particular
group of nodes.  For instance, we can move the index `test` to either `big` or
`medium` nodes as follows:

[source,json]
------------------------
PUT test/_settings
{
  "index.routing.allocation.include.size": "big,medium"
}
------------------------
// AUTOSENSE

Alternatively, we can move the index `test` away from the `small` nodes with
an `exclude` rule:

[source,json]
------------------------
PUT test/_settings
{
  "index.routing.allocation.exclude.size": "small"
}
------------------------
// AUTOSENSE

Multiple rules can be specified, in which case all conditions must be
satisfied.  For instance, we could move the index `test` to `big` nodes in
`rack1` with the following:

[source,json]
------------------------
PUT test/_settings
{
  "index.routing.allocation.include.size": "big",
  "index.routing.allocation.include.rack": "rack1"
}
------------------------
// AUTOSENSE

NOTE: If some conditions cannot be satisfied then shards will not be moved.

The following settings are _dynamic_, allowing live indices to be moved from
one set of nodes to another:

`index.routing.allocation.include.{attribute}`::

    Assign the index to a node whose `{attribute}` has at least one of the
    comma-separated values.

`index.routing.allocation.require.{attribute}`::

    Assign the index to a node whose `{attribute}` has _all_ of the
    comma-separated values.

`index.routing.allocation.exclude.{attribute}`::

    Assign the index to a node whose `{attribute}` has _none_ of the
    comma-separated values.

These special attributes are also supported:

[horizontal]
`_name`::   Match nodes by node name
`_ip`::     Match nodes by IP address (the IP address associated with the hostname)
`_host`::   Match nodes by hostname

All attribute values can be specified with wildcards, eg:

[source,json]
------------------------
PUT test/_settings
{
  "index.routing.allocation.include._ip": "192.168.2.*"
}
------------------------
// AUTOSENSE

[float]
=== Total Shards Per Node

The cluster-level shard allocator tries to spread the shards of a single index
across as many nodes as possible.  However, depending on how many shards and
indices you have, and how big they are, it may not always be possible to spread
shards evenly.

The following _dynamic_ setting allows you to specify a hard limit on the total
number of shards from a single index allowed per node:

`index.routing.allocation.total_shards_per_node`::

    The maximum number of shards (replicas and primaries) that will be
    allocated to a single node.  Defaults to unbounded.

[WARNING]
=======================================
This setting imposes a hard limit which can result in some shards not
being allocated.

Use with caution.
=======================================