Cluster Update Settings

Use this API to review and change cluster-wide settings.

To review cluster settings:

GET /_cluster/settings

Updates to settings can be persistent, meaning they apply across restarts, or transient, where they don’t survive a full cluster restart. Here is an example of a persistent update:

PUT /_cluster/settings
{
    "persistent" : {
        "indices.recovery.max_bytes_per_sec" : "50mb"
    }
}

This update is transient:

PUT /_cluster/settings?flat_settings=true
{
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : "20mb"
    }
}

The response to an update returns the changed setting, as in this response to the transient example:

{
    ...
    "persistent" : { },
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : "20mb"
    }
}

You can reset persistent or transient settings by assigning a null value. If a transient setting is reset, the first one of these values that is defined is applied:

  • the persistent setting
  • the setting in the configuration file
  • the default value.

This example resets a setting:

PUT /_cluster/settings
{
    "transient" : {
        "indices.recovery.max_bytes_per_sec" : null
    }
}

The response does not include settings that have been reset:

{
    ...
    "persistent" : {},
    "transient" : {}
}

You can also reset settings using wildcards. For example, to reset all dynamic indices.recovery settings:

PUT /_cluster/settings
{
    "transient" : {
        "indices.recovery.*" : null
    }
}

Order of Precedence

The order of precedence for cluster settings is:

  1. transient cluster settings
  2. persistent cluster settings
  3. settings in the elasticsearch.yml configuration file.

It’s best to use the elasticsearch.yml file only for local configurations, and set all cluster-wide settings with the settings API.

You can find the list of settings that you can dynamically update in Modules.