[[allocation]]
== allocation

[float]
Summary
~~~~~~~

From the
{ref}/index-modules-allocation.html#shard-allocation-filtering[Elasticsearch
Shard Allocation Filtering Documentation]:

________________________________________________________________________________
Allows to control the allocation of indices on nodes based on include/exclude
filters. The filters can be set both on the index level and on the cluster
level. Lets start with an example of setting it on the cluster level:

Lets say we have 4 nodes, each has specific attribute called `tag` associated
with it (the name of the attribute can be any name). Each node has a specific
value associated with `tag`. Node 1 has a setting `node.tag: value1`, Node 2 a
setting of `node.tag: value2`, and so on.

We can create an index that will only deploy on nodes that have tag set to
value1 and value2 by setting index.routing.allocation.include.tag to
value1,value2. For example:

------------------------------------------------------------
curl -XPUT localhost:9200/test/_settings -d '{
    "index.routing.allocation.include.tag" : "value1,value2"
}'
------------------------------------------------------------

On the other hand, we can create an index that will be deployed on all nodes
except for nodes with a `tag` of value `value3` by setting
`index.routing.allocation.exclude.tag` to `value3`. For example:

------------------------------------------------------------
curl -XPUT localhost:9200/test/_settings -d '\{ +
 "index.routing.allocation.exclude.tag" : "value3" +
}'
------------------------------------------------------------

`index.routing.allocation.require.*` can be used to specify a number of rules,
all of which MUST match in order for a shard to be allocated to a node.
________________________________________________________________________________

 

It is this last method, `index.routing.allocation.require.*`, that Curator uses
to force routing.  Curator does not use `include` or `exclude` tagging.

[float]
Use-case
^^^^^^^^

You may be wondering why this is useful.  Imagine that you have a tiered
Elasticsearch cluster, with indexing happening on nodes with SSDs, and
longer-term storage on nodes with traditional spinning hard disks.  Using
routing allocation, you can do indexing on the SSD nodes, then after a few days
use curator to shift them to change the routing allocation tags to re-allocate
them onto the slower storage nodes.

[float]
Extra configuration needed
^^^^^^^^^^^^^^^^^^^^^^^^^^

You can assign tags to your indices with Curator, but no allocation will occur
unless you have the tags set in each node's `elasticsearch.yml`:

SSD nodes:

    node.tag: ssd

Spinning disk nodes:

    node.tag: hdd

These tags can be anything.  You could use `fast` and `slow` if you wanted.
`tag` is only the example provided here. You can use other descriptive markers:

    node.disk_type: ssd

or

    node.disk_type: hdd

In like fashion, you would need to guarantee that new indexes are tagged with
the appropriate markers, e.g. `tag` and `ssd`.  This should be handled with an
Elasticsearch mapping template.  Logstash comes with one by default, but it has
no routing tags.  You can use that template as a guide and add the appropriate
tags.

[float]
Flags
~~~~~

--------------------------------------------------------------------------------

$ curator allocation --help
Usage: curator allocation [OPTIONS] COMMAND [ARGS]...

Index Allocation

Options:
 --rule TEXT Routing allocation rule to apply, e.g. tag=ssd
 --help Show this message and exit.

Commands:
 indices Index selection.
--------------------------------------------------------------------------------

 

IMPORTANT: This command requires the <<indices-subcommand,indices>>
<<subcommand,subcommand>> for <<index-selection,index selection>>.

[float]
Example
~~~~~~~

Apply the `tag` value of `hdd`:

------------------------------------------------------------------------
curator allocation --rule tag=hdd indices <<index selection parameters>>
------------------------------------------------------------------------

&nbsp;

This will append the setting `index.routing.allocation.require.tag=hdd` to the
indices specified by <<index-selection,index selection>>.