How to update cluster settings in Elasticsearch

Updating cluster settings in Elasticsearch changes cluster-wide behavior without modifying per-node configuration files, which is useful for maintenance windows, allocation tuning, and protecting clusters from operational problems caused by unsafe defaults or rapid growth.

Dynamic cluster settings are stored in the cluster state and are managed through the /_cluster/settings API using a JSON body. Values can be applied as persistent settings (survive restarts) or transient settings (cleared after a full cluster restart), and transient values override persistent values when both define the same key.

Cluster setting updates require cluster-level privileges, and secured clusters typically require HTTPS plus authentication. Only settings marked as dynamic can be changed through the API; static settings must be set in elasticsearch.yml and applied with a node restart. Incorrect values can prevent shard allocation or block index creation, so changes should be minimal, verified immediately, and rolled back by unsetting the key (null) when necessary.

1. Review current cluster settings.

   $ curl -sS "http://localhost:9200/_cluster/settings?flat_settings=true&pretty"
   {
     "persistent" : { },
     "transient" : { }
   }

   Replace http://localhost:9200 with the cluster endpoint, and add authentication/TLS options when security is enabled (for example --user and --cacert).

2. Set a persistent cluster setting.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "persistent": {
       "cluster.max_shards_per_node": 1500
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : {
       "cluster" : {
         "max_shards_per_node" : "1500"
       }
     },
     "transient" : { }
   }

   cluster.max_shards_per_node limits shard count per data node; increasing it reduces oversharding protection, decreasing it can block index creation.

3. Set a transient cluster setting.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "transient": {
       "logger.org.elasticsearch.discovery": "DEBUG"
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : { },
     "transient" : {
       "logger" : {
         "org" : {
           "elasticsearch" : {
             "discovery" : "DEBUG"
           }
         }
       }
     }
   }

   Setting loggers to DEBUG can rapidly increase log volume and consume disk space.

4. Verify the settings were applied.

   $ curl -sS "http://localhost:9200/_cluster/settings?flat_settings=true&pretty"
   {
     "persistent" : {
       "cluster.max_shards_per_node" : "1500"
     },
     "transient" : {
       "logger.org.elasticsearch.discovery" : "DEBUG"
     }
   }

5. Remove the persistent setting by setting its value to null.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "persistent": {
       "cluster.max_shards_per_node": null
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : { },
     "transient" : { }
   }

   Unsetting a key falls back to the default value or the value set outside cluster state.

6. Remove the transient setting by setting its value to null.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "transient": {
       "logger.org.elasticsearch.discovery": null
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : { },
     "transient" : { }
   }

7. Confirm removed settings are no longer present in the cluster settings output.

   $ curl -sS "http://localhost:9200/_cluster/settings?flat_settings=true&pretty"
   {
     "persistent" : { },
     "transient" : { }
   }