OpenSearch/docs/reference/ilm/actions/ilm-allocate.asciidoc

[role="xpack"]
[[ilm-allocate]]
=== Allocate

Phases allowed: warm, cold, frozen.

Updates the index settings to change which nodes are allowed to host the index shards
and change the number of replicas.

The allocate action is not allowed in the hot phase. 
The initial allocation for the index must be done manually or via 
<<indices-templates, index templates>>.

You can configure this action to modify both the allocation rules and number of replicas, 
only the allocation rules, or only the number of replicas. 
For more information about how {es} uses replicas for scaling, see
<<scalability>>. See <<shard-allocation-filtering>> for more information about
controlling where {es} allocates shards of a particular index.


[[ilm-allocate-options]]
==== Options

You must specify the number of replicas or at least one 
`include`, `exclude`, or `require` option. 
An empty allocate action is invalid.

For more information about using custom attributes for shard allocation, 
see <<shard-allocation-filtering>>.

`number_of_replicas`::
(Optional, integer)
Number of replicas to assign to the index.

`include`::
(Optional, object)
Assigns an index to nodes that have at least _one_ of the specified custom attributes.

`exclude`::
(Optional, object)
Assigns an index to nodes that have _none_ of the specified custom attributes.

`require`::
(Optional, object)
Assigns an index to nodes that have _all_ of the specified custom attributes.

[[ilm-allocate-ex]]
==== Example

The allocate action in the following policy changes the index's number of replicas to `2`. 
The index allocation rules are not changed.

[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas" : 2
          }
        }
      }
    }
  }
}
--------------------------------------------------

[[ilm-allocate-assign-index-attribute-ex]]
===== Assign index to nodes using a custom attribute

The allocate action in the following policy assigns the index to nodes 
that have a `box_type` of _hot_ or _warm_.

To designate a node's `box_type`, you set a custom attribute in the node configuration.
For example, set `node.attr.box_type: hot` in `elasticsearch.yml`. 
For more information, see <<index-allocation-filters>>.

[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "include" : {
              "box_type": "hot,warm"
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------

[[ilm-allocate-assign-index-node-ex]]
===== Assign index to a specific node and update replica settings

The allocate action in the following policy updates the index to have one replica per shard 
and be allocated to nodes that have a `box_type` of _cold_. 

To designate a node's `box_type`, you set a custom attribute in the node configuration.
For example, set `node.attr.box_type: cold` in `elasticsearch.yml`. 
For more information, see <<index-allocation-filters>>.

[source,console]
--------------------------------------------------
PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas": 1,
            "require" : {
              "box_type": "cold"
            }
        }
        }
      }
    }
  }
}
--------------------------------------------------