Elasticsearch Optimizing Elasticsearch Cluster with the Reroute API

By Opster Team

Updated: Nov 14, 2023

| 3 min read

Introduction

In this article, we will discuss the various options available with the Reroute API and provide examples of how to use them effectively. If you want to learn about rerouting shards: – how to solve related issues, check out this guide.  

Understanding the Reroute API

The Reroute API provides a set of commands that can be used to manipulate the allocation of shards within an Elasticsearch cluster. These commands include:

1. move: Moves a shard from one node to another.
2. allocate_replica: Allocates an unassigned replica shard to a specific node.
3. cancel: Cancels the allocation of a shard that is in the process of being moved or allocated.
4. allocate_stale_primary: Allocates a stale primary shard to a specific node, allowing you to recover data from a failed primary shard.
5. allocate_empty_primary: Allocates an empty primary shard to a specific node, allowing you to recover from a situation where all copies of a shard have been lost.

Using the Reroute API

To use the Reroute API, you need to send a POST request to the `_cluster/reroute` endpoint, along with a JSON payload containing the commands you want to execute. Here are some examples of how to use the Reroute API with different commands:

1. Move a shard:

To move a shard from one node to another, you can use the `move` command. For example, to move shard 0 of index “my_index” from node “node1” to node “node2”, you would send the following request:

POST /_cluster/reroute
{
  "commands": [
    {
      "move": {
        "index": "my_index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2"
      }
    }
  ]
}

2. Allocate an unassigned replica shard:

If you have an unassigned shard that you want to allocate to a specific node, you can use the `allocate_replica` command. For example, to allocate shard 1 of index “my_index” to node “node1”, you would send the following request:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_replica": {
        "index": "my_index",
        "shard": 1,
        "node": "node1"
      }
    }
  ]
}

3. Cancel a shard allocation:

To cancel the allocation of a shard that is in the process of being moved or allocated, you can use the `cancel` command. For example, to cancel the allocation of shard 2 of index “my_index” on node “node1”, you would send the following request:

POST /_cluster/reroute
{
  "commands": [
    {
      "cancel": {
        "node": "node1",
        "index": "my_index",
        "shard": 2
      }
    }
  ]
}

4. Allocate a stale primary shard:

In cases where a primary shard has failed, and you want to recover data from a stale primary shard, you can use the `allocate_stale_primary` command. For example, to allocate the stale primary shard 0 of index “my_index” to node “node1”, you would send the following request:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_stale_primary": {
        "index": "my_index",
        "shard": 0,
        "node": "node1",
        "accept_data_loss": true
      }
    }
  ]
}

Since running this command may lead to data loss for the provided shard, the `accept_data_loss` flag set to true is mandatory in order to acknowledge that you have fully understood the implications.

5. Allocate an empty primary shard:

If all copies of a shard have been lost, and you want to recover by allocating an empty primary shard, you can use the `allocate_empty_primary` command. For example, to allocate an empty primary shard 1 of index “my_index” to node “node1”, you would send the following request:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "my_index",
        "shard": 1,
        "node": "node1",
        "accept_data_loss": true
      }
    }
  ]
}

Since running this command may lead to data loss for the provided shard, the `accept_data_loss` flag set to true is mandatory in order to acknowledge that you have fully understood the implications.

Conclusion

The Elasticsearch Reroute API provides a powerful way to manually control the allocation of shards within your cluster. By understanding the various commands available and how to use them effectively, you can optimize your cluster for performance, recover from node failures, and balance the distribution of shards across nodes. Always be cautious when using the Reroute API, as improper use can lead to data loss or cluster instability.