The index.routing.allocation.include._name setting in Elasticsearch controls shard allocation based on node names. It allows you to specify which nodes are eligible to host shards of a particular index.
- Default value: Not set (allows allocation to any node)
- Possible values: Comma-separated list of node names or wildcards
- Recommendation: Use sparingly and in conjunction with other allocation settings for fine-grained control
This setting is part of the index-level shard allocation filtering mechanism. When set, it restricts the allocation of the index's shards to nodes whose names match the specified values or patterns.
Example
To allocate shards of an index only to nodes named "node1" and "node2":
PUT /my-index/_settings
{
"index.routing.allocation.include._name": "node1,node2"
}
You might want to change this setting to:
- Ensure certain indices are only on specific nodes (e.g., nodes with SSDs)
- Implement a form of data locality or isolation
- Gradually migrate data off nodes that will be decommissioned
The effect of this change is that Elasticsearch will only allocate new shards or relocate existing shards of the index to the specified nodes.
Common Issues and Misuses
- Over-constraining shard allocation, leading to unbalanced cluster or allocation failures
- Forgetting to update the setting when adding new nodes, potentially preventing proper scaling
- Using this setting without considering other allocation rules, which may conflict
Do's and Don'ts
- Do use this setting in combination with other allocation rules for more flexible control
- Do regularly review and update these settings as your cluster evolves
- Don't rely solely on this setting for critical allocation decisions
- Don't use overly restrictive patterns that might prevent proper shard distribution
Frequently Asked Questions
Q: Can I use wildcards in the node name patterns?
A: Yes, you can use wildcards. For example, "data-*" would match all nodes with names starting with "data-".
Q: What happens if no nodes match the specified names?
A: If no nodes match, the shards will remain unassigned until matching nodes become available or the setting is changed.
Q: How does this setting interact with other allocation settings?
A: This setting is combined with other allocation settings using AND logic. All conditions must be met for a shard to be allocated to a node.
Q: Can I use this setting to move shards off a node?
A: Yes, by setting it to exclude a specific node name, you can trigger shard migration away from that node.
Q: Is this setting dynamic, or does it require a restart?
A: This is a dynamic setting that can be updated on a live index without requiring a restart.
