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

While <<index-modules-allocation>> provides *per-index* settings to control the
allocation of shards to nodes, cluster-level shard allocation filtering allows
you to allow or disallow the allocation of shards from *any* index to
particular nodes.

The available _dynamic_ cluster settings are as follows, where `{attribute}`
refers to an arbitrary node attribute.:

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

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

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

    Only allocate shards to a node whose `{attribute}` has _all_ of the
    comma-separated values.

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

    Do not allocate shards to a node whose `{attribute}` has _none_ of the
    comma-separated values.

These special attributes are also supported:

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

The typical use case for cluster-wide shard allocation filtering is when you
want to decommission a node, and you would like to move the shards from that
node to other nodes in the cluster before shutting it down.

For instance, we could decommission a node using its IP address as follows:

[source,js]
--------------------------------------------------
PUT _cluster/settings
{
  "transient" : {
    "cluster.routing.allocation.exclude._ip" : "10.0.0.1"
  }
}
--------------------------------------------------
// CONSOLE

NOTE: Shards will only be relocated if it is possible to do so without
breaking another routing constraint, such as never allocating a primary and
replica shard to the same node.

In addition to listing multiple values as a comma-separated list, all
attribute values can be specified with wildcards, eg:

[source,js]
------------------------
PUT _cluster/settings
{
  "transient": {
    "cluster.routing.allocation.exclude._ip": "192.168.2.*"
  }
}
------------------------
// CONSOLE
// TEST[skip:indexes don't assign]
