Cluster update settings API
editCluster update settings API
editConfigures dynamic cluster settings.
Request
editPUT /_cluster/settings
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
managecluster privilege to use this API.
Description
editYou can configure and update dynamic settings on a running cluster using the
cluster update settings API.
You can also configure dynamic settings locally on an unstarted or shut down
node using elasticsearch.yml.
Updates made using the cluster update settings API can be persistent, which
apply across cluster restarts, or transient, which reset after a cluster
restart. You can also reset transient or persistent settings by assigning them
a null value using the API.
If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence:
- Transient setting
- Persistent setting
-
elasticsearch.ymlsetting - Default setting value
For example, you can apply a transient setting to override a persistent setting
or elasticsearch.yml setting. However, a change to an elasticsearch.yml
setting will not override a defined transient or persistent setting.
If you use Elasticsearch Service, use the user settings feature to configure all cluster settings. This method lets Elasticsearch Service automatically reject unsafe settings that could break your cluster.
If you run Elasticsearch on your own hardware, use the
cluster update settings API
to configure dynamic cluster settings. Only use elasticsearch.yml for static
cluster settings and node settings. The API doesn’t require a restart and
ensures a setting’s value is the same on all nodes.
We no longer recommend using transient cluster settings. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration. See the Transient settings migration guide.
Query parameters
edit-
flat_settings -
(Optional, Boolean) If
true, returns settings in flat format. Defaults tofalse. -
include_defaults -
(Optional, Boolean) If
true, returns all default cluster settings. Defaults tofalse. -
master_timeout -
(Optional, time units)
Period to wait for a connection to the master node. If no response is received
before the timeout expires, the request fails and returns an error. Defaults to
30s. -
timeout -
(Optional, time units)
Period to wait for a response. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to
30s.
Examples
editAn example of a persistent update:
PUT /_cluster/settings
{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}
An example of a transient update:
We no longer recommend using transient cluster settings. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration. See the Transient settings migration guide.
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"
}
}
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
}
}