Shard allocation filtering

Shard allocation filtering lets you constrain where shards for an index are placed by matching node attributes. You can use it to pin shards to certain nodes, avoid nodes, or require specific hardware or zones. Shards are only allocated to nodes that satisfy all active filters, including index-level shard allocation filtering and cluster-level routing awareness.

Endpoints

PUT /<index>/_settings
GET /<index>/_settings

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Built-in and custom attributes

You can filter on built‑in attributes or any custom node attribute you define. For example, custom attribute can be defined by adding node.attr.zone: zone-a in opensearch.yml. The following built‑in attributes are supported.

Filter types

Use the following index settings.

Example requests

The following examples demonstrate the different ways to use shard allocation filters.

Allocate an index only to a specific zone

Use the following command to allocate an index to nodes in zone-a:

PUT /test-index/_settings
{
  "index.routing.allocation.require.zone": "zone-a"
}

Allocate to a subset of nodes by IPs

PUT /test-index/_settings
{
  "index.routing.allocation.include._ip": "10.0.0.12,10.0.0.13"
}

Exclude an index from the node

The following command excludes an index from node data-node-3:

PUT /test-index/_settings
{
  "index.routing.allocation.exclude._name": "data-node-3"
}

Combine filters

The following command configures required rack but excludes node data-node-7:

PUT /test-index/_settings
{
  "index": {
    "routing.allocation.require.rack": "r1",
    "routing.allocation.exclude._name": "data-node-7"
  }
}

Clear a filter

To clear a filter, set its value to null or an empty string "":

PUT /test-index/settings
{
  "persistent": {
    "index.routing.allocation.exclude._host_ip": null
  }
}

Example response

{
  "acknowledged": true
}