Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update update-settings.asciidoc #31378

Merged
merged 1 commit into from
Jul 26, 2018
Merged

Update update-settings.asciidoc #31378

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 34 additions & 30 deletions docs/reference/cluster/update-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,18 @@
[[cluster-update-settings]]
== Cluster Update Settings

Allows to update cluster wide specific settings. Settings updated can
either be persistent (applied across restarts) or transient (will not
survive a full cluster restart). Here is an example:
Use this API to review and change cluster-wide settings.

To review cluster settings:

[source,js]
--------------------------------------------------
GET /_cluster/settings
--------------------------------------------------
// CONSOLE

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:

[source,js]
--------------------------------------------------
Expand All @@ -16,7 +25,7 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE

Or:
This update is transient:

[source,js]
--------------------------------------------------
Expand All @@ -29,8 +38,7 @@ PUT /_cluster/settings?flat_settings=true
--------------------------------------------------
// CONSOLE

The cluster responds with the settings updated. So the response for the
last example will be:
The response to an update returns the changed setting, as in this response to the transient example:

[source,js]
--------------------------------------------------
Expand All @@ -44,11 +52,14 @@ last example will be:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]

Resetting persistent or transient settings can be done by assigning a
`null` value. If a transient setting is reset, the persistent setting
is applied if available. Otherwise Elasticsearch will fallback to the setting
defined at the configuration file or, if not existent, to the default
value. Here is an example:
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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "If a transient setting is reset..." sentence makes it sound like transient settings are somehow special. I think this section would make more sense if it were to appear after the Order of Precedence section.


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

This example resets a setting:

[source,js]
--------------------------------------------------
Expand All @@ -61,8 +72,7 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE

Reset settings will not be included in the cluster response. So
the response for the last example will be:
The response does not include settings that have been reset:

[source,js]
--------------------------------------------------
Expand All @@ -74,8 +84,8 @@ the response for the last example will be:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]

Settings can also be reset using simple wildcards. For instance to reset
all dynamic `indices.recovery` setting a prefix can be used:
You can also reset settings using wildcards. For example, to reset
all dynamic `indices.recovery` settings:

[source,js]
--------------------------------------------------
Expand All @@ -88,25 +98,19 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE

Cluster wide settings can be returned using:

[source,js]
--------------------------------------------------
GET /_cluster/settings
--------------------------------------------------
// CONSOLE

[float]
=== Precedence of settings
=== Order of Precedence

The order of precedence for cluster settings is:

Transient cluster settings take precedence over persistent cluster settings,
which take precedence over settings configured in the `elasticsearch.yml`
config file.
1. transient cluster settings
2. persistent cluster settings
3. settings in the `elasticsearch.yml` configuration file.

For this reason it is preferrable to use the `elasticsearch.yml` file only
for local configurations, and set all cluster-wider settings with the
It's best to use the `elasticsearch.yml` file only
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps expand on this: the reason why it is better to use cluster settings instead of settings in the config file is that you can be sure that the setting is the same on all nodes. If different nodes have different settings, and you don't use cluster settings, there is no way of knowing about these discrepancies.

for local configurations, and set all cluster-wide settings with the
`settings` API.

A list of dynamically updatable settings can be found in the
<<modules,Modules>> documentation.
You can find the list of settings that you can dynamically update in <<modules,Modules>>.