Elasticsearch cluster.routing.allocation.enable: Values, Default, and Rolling Restart Use

The cluster.routing.allocation.enable setting is the global on/off switch for shard allocation in an Elasticsearch cluster. It defaults to all, meaning every kind of shard - primary, replica, new index, existing index - is allowed to be allocated to data nodes. The setting accepts four values (all, primaries, new_primaries, none) and is most commonly toggled to none during a rolling restart or upgrade to prevent the cluster from rebuilding replicas every time a node leaves the cluster briefly.

Definition

cluster.routing.allocation.enable is a dynamic cluster-level setting that gates the shard allocator. When set to anything other than all, the allocator refuses to assign certain classes of shard, even when assignments are otherwise possible. The setting affects allocation decisions only; existing healthy shards are not moved, and the setting does not block writes.

Default and Allowed Values

The setting is dynamic and takes effect immediately on update. It does not require a restart and does not flush in-flight allocations - relocations already underway will complete.

How to Change It

Through the cluster settings API. Persistent vs transient determines whether the value survives a full cluster restart:

# Standard rolling-restart prep: stop allocation entirely
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "none"
  }
}

# Re-enable after the restart
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": null
  }
}

Setting the value to null removes the override and reverts to the default of all. Use persistent for changes you want to survive a full cluster restart; use transient only when you want the setting cleared automatically on full restart (less common, and deprecated in favour of persistent settings on newer versions).

Inspect the current value:

GET /_cluster/settings?include_defaults=true&filter_path=*.cluster.routing.allocation.enable

Standard Use Case: Rolling Restart

The canonical workflow:

1. Disable shard allocation: PUT /_cluster/settings {"persistent": {"cluster.routing.allocation.enable": "none"}}.
2. (Optional) Flush the translog to speed up recovery: POST /_flush/synced (pre-7.6) or POST /_flush on 7.6+.
3. Stop the target node and perform the upgrade or maintenance.
4. Start the node and wait for it to join the cluster.
5. Re-enable allocation: PUT /_cluster/settings {"persistent": {"cluster.routing.allocation.enable": null}}.
6. Wait for cluster health to return to green before moving to the next node.

Skipping step 1 causes the cluster to start rebuilding replicas onto other nodes as soon as the target node leaves, then move them back when it returns - wasteful network and disk I/O.

Operational Impact

• all is the normal operating value. Allocation, rebalancing, and recovery proceed as usual.
• primaries keeps primary shards allocatable but blocks replica allocation. Useful when recovering from a serious failure where you want primaries to come up but want to defer the cost of rebuilding replicas.
• new_primaries is narrower still: only primaries of newly created indices. Existing unassigned primaries stay unassigned. Almost never the right choice outside specific recovery scenarios.
• none blocks everything. Useful for maintenance, but leaving it set causes any unassigned shard to stay unassigned, eventually leading to yellow then red cluster status if nodes fail.

A common operator mistake is to set none for a restart, forget to revert it, and only discover the issue when a later failure reveals shards stuck unassigned. Always pair the disable with the revert step in the same runbook.

Common Mistakes

1. Forgetting to revert to all after a maintenance window. Set a calendar reminder if your runbook lacks one.
2. Using transient for this setting. A full cluster restart silently re-enables allocation in the middle of your upgrade. Prefer persistent.
3. Setting none to mitigate shard churn from a real problem. This hides the symptom (frequent rebalancing) without fixing the cause (unbalanced disks, hot shards, wrong allocation filters).
4. Confusing with cluster.routing.rebalance.enable. Allocation moves new or unassigned shards; rebalance moves already-assigned shards to even the load. The two are independent.

Prevent Forgotten allocation.enable: none with Pulse

Pulse is an AI DBA for Elasticsearch and OpenSearch that tracks cluster.routing.allocation.enable continuously, flagging:

• Drift between the operating default all and any other value left in place (the classic "set none for a rolling restart and forgot to revert" pattern)
• Settings that are unsafe for your workload (e.g. primaries or new_primaries left after a partial recovery, or transient used where a full cluster restart would silently revert in the middle of an upgrade)
• The downstream operational impact: unassigned shards accumulating, cluster status drift to yellow or red, allocation blocked according to _cluster/allocation/explain

When a maintenance window ends but the runbook missed the revert step, Pulse names the cluster and the operator-set override before the next failure exposes shards stuck unassigned.

Connect your cluster.

Frequently Asked Questions

Q: What is the default value of cluster.routing.allocation.enable?
A: The default is all, which allows allocation of every kind of shard. The other valid values are primaries, new_primaries, and none. The setting is dynamic and can be changed without restarting.

Q: How do I temporarily disable shard allocation for a rolling restart?
A: Set cluster.routing.allocation.enable to none before stopping nodes, perform the restart, then revert to all (or null) afterwards. This prevents Elasticsearch from rebuilding replicas while nodes are briefly absent.

Q: What is the difference between primaries and new_primaries?
A: primaries allows allocation of all primary shards, including primaries of existing indices that are currently unassigned. new_primaries only allows allocation of primaries for newly created indices; existing unassigned primaries stay unassigned. The distinction matters during recovery from partial cluster failure.

Q: Does cluster.routing.allocation.enable block writes?
A: No. It blocks shard allocation decisions only. If a shard is already allocated and healthy, it continues to accept writes. Writes only fail if the relevant shard is unassigned and cannot be allocated because of this setting.

Q: How is cluster.routing.allocation.enable different from cluster.routing.rebalance.enable?
A: Allocation governs the assignment of unassigned shards to nodes (new indices, recoveries, node joins). Rebalance governs the relocation of already-assigned shards between nodes to even out load. They are independent settings; for a full freeze of shard movement set both to none.

Q: Can I see whether shard allocation is enabled?
A: Yes. GET /_cluster/settings?include_defaults=true returns the current value, including the default if you have not overridden it. GET /_cluster/allocation/explain will also tell you when an unassigned shard is being held back by this setting.

Q: What's the best tool to catch forgotten cluster.routing.allocation.enable overrides?
A: Pulse is built for this. It is an AI DBA for Elasticsearch and OpenSearch that continuously checks cluster.routing.allocation.enable across clusters, flags any value other than all left in place after a maintenance window, and correlates with unassigned shards from _cluster/allocation/explain so the misconfiguration is named before it causes an outage.

Related Reading

• Elasticsearch cluster.routing.rebalance.enable Setting
• Elasticsearch cluster.routing.allocation.node_concurrent_recoveries
• Elasticsearch cluster.routing.allocation.disk.watermark.high
• Elasticsearch Cluster Status Yellow
• Elasticsearch Cluster Health Check
• Elasticsearch cluster.initial_master_nodes Setting