IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Allocate

edit

Allocate

edit

Phases allowed: warm, cold.

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 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 Elasticsearch uses replicas for scaling, see Scalability and resilience. See Index-level shard allocation filtering for more information about controlling where Elasticsearch allocates shards of a particular index.

Options

edit

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 Index-level shard allocation filtering.

number_of_replicas: (Optional, integer) Number of replicas to assign to the index.
total_shards_per_node: (Optional, integer) The maximum number of shards for the index on a single Elasticsearch node. A value of -1 is interpreted as unlimited. See total shards.
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.

Example

edit

The allocate action in the following policy changes the index’s number of replicas to 2. No more than 200 shards for the index will be placed on any single node. Otherwise the index allocation rules are not changed.

response = client.ilm.put_lifecycle(
  policy: 'my_policy',
  body: {
    policy: {
      phases: {
        warm: {
          actions: {
            allocate: {
              number_of_replicas: 2,
              total_shards_per_node: 200
            }
          }
        }
      }
    }
  }
)
puts response

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas" : 2,
            "total_shards_per_node" : 200
          }
        }
      }
    }
  }
}

Assign index to nodes using a custom attribute

edit

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 Enabling index-level shard allocation filtering.

response = client.ilm.put_lifecycle(
  policy: 'my_policy',
  body: {
    policy: {
      phases: {
        warm: {
          actions: {
            allocate: {
              include: {
                box_type: 'hot,warm'
              }
            }
          }
        }
      }
    }
  }
)
puts response

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "include" : {
              "box_type": "hot,warm"
            }
          }
        }
      }
    }
  }
}

Assign index to nodes based on multiple attributes

edit

The allocate action can also assign indices to nodes based on multiple node attributes. The following action assigns indices based on the box_type and storage node attributes.

response = client.ilm.put_lifecycle(
  policy: 'my_policy',
  body: {
    policy: {
      phases: {
        cold: {
          actions: {
            allocate: {
              require: {
                box_type: 'cold',
                storage: 'high'
              }
            }
          }
        }
      }
    }
  }
)
puts response

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "cold": {
        "actions": {
          "allocate" : {
            "require" : {
              "box_type": "cold",
              "storage": "high"
            }
          }
        }
      }
    }
  }
}

Assign index to a specific node and update replica settings

edit

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 Enabling index-level shard allocation filtering.

response = client.ilm.put_lifecycle(
  policy: 'my_policy',
  body: {
    policy: {
      phases: {
        warm: {
          actions: {
            allocate: {
              number_of_replicas: 1,
              require: {
                box_type: 'cold'
              }
            }
          }
        }
      }
    }
  }
)
puts response

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas": 1,
            "require" : {
              "box_type": "cold"
            }
        }
        }
      }
    }
  }
}

« Index lifecycle actions Delete »