How to update cluster settings in Elasticsearch

Updating cluster settings in Elasticsearch changes cluster-wide behavior without editing each node separately or waiting for a restart, which is useful when tuning recovery throughput, adjusting allocation rules, or applying temporary operational safeguards during maintenance.

Dynamic cluster settings are managed through the /_cluster/settings API. Elasticsearch stores API-based changes as persistent or transient overrides, and applies them in this order of precedence: transient, persistent, elasticsearch.yml, then the built-in default.

Current Elastic guidance is to use persistent settings for normal operations because transient settings can clear unexpectedly if the cluster becomes unstable. Only settings marked as dynamic can be changed through the API; static settings still belong in elasticsearch.yml. Secure clusters typically require https plus authentication, and Elastic Cloud Hosted or ECE deployments are generally safer to manage through deployment user settings rather than the raw API.

1. Review the current effective value for the target setting.

   $ curl -sS "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.indices.recovery.max_bytes_per_sec,persistent.indices.recovery.max_bytes_per_sec,transient.indices.recovery.max_bytes_per_sec&pretty"
   {
     "defaults" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "40mb"
         }
       }
     }
   }

   GET /_cluster/settings returns only explicitly defined settings by default. Add include_defaults=true to see the fallback value, replace http://localhost:9200 with the cluster endpoint plus authentication or TLS options when security is enabled, and use a credential with cluster monitor privilege for this read call on secured clusters.

2. Apply a persistent cluster setting.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "persistent": {
       "indices.recovery.max_bytes_per_sec": "50mb"
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "50mb"
         }
       }
     },
     "transient" : { }
   }

   persistent settings survive cluster restarts and are the recommended default for dynamic configuration changes.

   Use a credential with cluster manage privilege for update calls on secured clusters.

   Related: How to configure Elasticsearch recovery throttling

3. Read the setting again to confirm the persistent override is now defined.

   $ curl -sS "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.indices.recovery.max_bytes_per_sec,persistent.indices.recovery.max_bytes_per_sec,transient.indices.recovery.max_bytes_per_sec&pretty"
   {
     "persistent" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "50mb"
         }
       }
     }
   }

   Once a persistent or transient value exists, the matching defaults value is not repeated in this filtered response.

4. Apply a transient override only when a short-lived change is required.

   $ curl -sS -H "Content-Type: application/json" -X PUT "http://localhost:9200/_cluster/settings?pretty" -d '{
     "transient": {
       "indices.recovery.max_bytes_per_sec": "60mb"
     }
   }'
   {
     "acknowledged" : true,
     "persistent" : { },
     "transient" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "60mb"
         }
       }
     }
   }

   Elastic no longer recommends transient cluster settings for routine operations because they can clear unexpectedly if the cluster becomes unstable.

5. Verify the transient value overrides the persistent value.

   $ curl -sS "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.indices.recovery.max_bytes_per_sec,persistent.indices.recovery.max_bytes_per_sec,transient.indices.recovery.max_bytes_per_sec&pretty"
   {
     "persistent" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "50mb"
         }
       }
     },
     "transient" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "60mb"
         }
       }
     }
   }

   The effective value is now the transient override (60mb), even though the persistent value remains stored.

6. Clear the transient override when the temporary change is no longer needed.

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

   The update response only shows the sections changed by that request. Read the setting again to confirm which value is still effective.

7. Read the setting again to confirm the persistent value is effective after clearing the transient override.

   $ curl -sS "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.indices.recovery.max_bytes_per_sec,persistent.indices.recovery.max_bytes_per_sec,transient.indices.recovery.max_bytes_per_sec&pretty"
   {
     "persistent" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "50mb"
         }
       }
     }
   }

8. Clear the persistent override to return to the cluster default or the value from elasticsearch.yml.

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

   Assigning null removes the explicit override rather than setting the literal string null.

9. Confirm the cluster has fallen back to the default value.

   $ curl -sS "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=defaults.indices.recovery.max_bytes_per_sec,persistent.indices.recovery.max_bytes_per_sec,transient.indices.recovery.max_bytes_per_sec&pretty"
   {
     "defaults" : {
       "indices" : {
         "recovery" : {
           "max_bytes_per_sec" : "40mb"
         }
       }
     }
   }

   For a production change, finish by checking the subsystem affected by the setting, such as shard recovery speed, allocation behavior, or index creation, instead of relying only on the settings API output.