How to control shard allocation in Elasticsearch

Shard allocation control in Elasticsearch changes whether the cluster assigns primary shards, replica shards, or no future shard copies while maintenance is in progress. It is useful before rolling node restarts, short freezes, and recovery windows where replica movement would create avoidable disk and network load.

The dynamic setting cluster.routing.allocation.enable is changed through the Cluster Settings API at /_cluster/settings. It affects future allocation decisions only, so it does not remove shards that are already assigned to nodes or stop a restarted node from recovering a matching local primary shard from disk.

Use primaries for ordinary rolling maintenance because primary recovery can continue while replica assignment is paused. Use none only when every new shard assignment must stop, and clear both persistent and transient overrides as soon as the maintenance window ends.

1. Review the current effective allocation mode.

   $ curl -sS --fail --user elastic:password \
     "https://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.cluster.routing.allocation.enable,persistent.cluster.routing.allocation.enable,transient.cluster.routing.allocation.enable&pretty"
   {
     "defaults" : {
       "cluster" : {
         "routing" : {
           "allocation" : {
             "enable" : "all"
           }
         }
       }
     }
   }

   Elasticsearch applies transient settings before persistent settings, then elasticsearch.yml, then the default. The supported values are all, primaries, new_primaries, and none. Use cluster monitor privilege for this read call, and drop --user only on clusters that intentionally run without security.

2. Restrict allocation to primaries before a rolling restart or a short maintenance change.

   $ curl -sS --fail --user elastic:password \
     -H "Content-Type: application/json" -X PUT "https://localhost:9200/_cluster/settings?pretty" -d '{
     "persistent": {
       "cluster.routing.allocation.enable": "primaries"
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : {
       "cluster" : {
         "routing" : {
           "allocation" : {
             "enable" : "primaries"
           }
         }
       }
     },
     "transient" : { }
   }

   Primaries is the Elastic-documented rolling maintenance mode. It pauses replica allocation while still allowing primary shard allocation, and update calls require cluster manage privilege.
   Related: How to run a rolling upgrade for Elasticsearch
   Related: How to update cluster settings in Elasticsearch

3. Read the setting again to confirm primaries is active.

   $ curl -sS --fail --user elastic:password \
     "https://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.cluster.routing.allocation.enable,persistent.cluster.routing.allocation.enable,transient.cluster.routing.allocation.enable&pretty"
   {
     "persistent" : {
       "cluster" : {
         "routing" : {
           "allocation" : {
             "enable" : "primaries"
           }
         }
       }
     }
   }

   Replica shards can remain unassigned while primaries is set, which is expected until full allocation returns.

4. Pause all future shard allocations only when a full freeze is required.

   $ curl -sS --fail --user elastic:password \
     -H "Content-Type: application/json" -X PUT "https://localhost:9200/_cluster/settings?pretty" -d '{
     "persistent": {
       "cluster.routing.allocation.enable": "none"
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : {
       "cluster" : {
         "routing" : {
           "allocation" : {
             "enable" : "none"
           }
         }
       }
     },
     "transient" : { }
   }

   None stops future primary and replica assignments. Existing shard placements stay where they are, but new indices and rollover-created indices can remain unassigned until allocation returns.

5. Restore normal allocation by clearing explicit allocation overrides.

   $ curl -sS --fail --user elastic:password \
     -H "Content-Type: application/json" -X PUT "https://localhost:9200/_cluster/settings?pretty" -d '{
     "transient": {
       "cluster.routing.allocation.enable": null
     },
     "persistent": {
       "cluster.routing.allocation.enable": null
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : { },
     "transient" : { }
   }

   Assigning null removes stored overrides. If elasticsearch.yml intentionally pins cluster.routing.allocation.enable to a restrictive value, change that file separately or set an explicit all override for the emergency recovery window.

6. Check cluster recovery after allocation is restored.

   $ curl -sS --fail --user elastic:password \
     "https://localhost:9200/_cluster/health?filter_path=status,relocating_shards,initializing_shards,unassigned_shards,active_shards_percent_as_number&pretty"
   {
     "status" : "green",
     "relocating_shards" : 0,
     "initializing_shards" : 0,
     "unassigned_shards" : 0,
     "active_shards_percent_as_number" : 100.0
   }

   Yellow is still expected while replicas are reassigning or on a single-node cluster that cannot place replicas. Persistent unassigned shards after allocation is restored usually mean another allocation decider is blocking placement.
   Related: How to monitor Elasticsearch cluster health
   Related: How to explain shard allocation decisions in Elasticsearch