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
manage
cluster 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.yml
setting - 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 the master node. If the master node is not available before
the timeout expires, the request fails and returns an error. Defaults to
30s
. Can also be set to-1
to indicate that the request should never timeout. -
timeout
-
(Optional, time units) Period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.
If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged.
Defaults to
30s
. Can also be set to-1
to indicate that the request should never timeout.
Examples
editAn example of a persistent update:
resp = client.cluster.put_settings( persistent={ "indices.recovery.max_bytes_per_sec": "50mb" }, ) print(resp)
response = client.cluster.put_settings( body: { persistent: { 'indices.recovery.max_bytes_per_sec' => '50mb' } } ) puts response
const response = await client.cluster.putSettings({ persistent: { "indices.recovery.max_bytes_per_sec": "50mb", }, }); console.log(response);
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.
resp = client.cluster.put_settings( flat_settings=True, transient={ "indices.recovery.max_bytes_per_sec": "20mb" }, ) print(resp)
response = client.cluster.put_settings( flat_settings: true, body: { transient: { 'indices.recovery.max_bytes_per_sec' => '20mb' } } ) puts response
const response = await client.cluster.putSettings({ flat_settings: "true", transient: { "indices.recovery.max_bytes_per_sec": "20mb", }, }); console.log(response);
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:
resp = client.cluster.put_settings( transient={ "indices.recovery.max_bytes_per_sec": None }, ) print(resp)
response = client.cluster.put_settings( body: { transient: { 'indices.recovery.max_bytes_per_sec' => nil } } ) puts response
const response = await client.cluster.putSettings({ transient: { "indices.recovery.max_bytes_per_sec": null, }, }); console.log(response);
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:
resp = client.cluster.put_settings( transient={ "indices.recovery.*": None }, ) print(resp)
response = client.cluster.put_settings( body: { transient: { "indices.recovery.*": nil } } ) puts response
const response = await client.cluster.putSettings({ transient: { "indices.recovery.*": null, }, }); console.log(response);
PUT /_cluster/settings { "transient" : { "indices.recovery.*" : null } }