Skip to content

[DOCS] Reformats cluster update settings API #45337

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

Merged
szabosteve merged 2 commits into from
Aug 13, 2019
Merged

[DOCS] Reformats cluster update settings API #45337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6beac7
[DOCS] Reformats cluster update API.
szabosteve Aug 8, 2019
e6f59dd
Splits GET and PUT cluster settings APIs.
szabosteve Aug 12, 2019
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
40 changes: 23 additions & 17 deletions docs/reference/cluster/get-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,26 @@
[[cluster-get-settings]]
=== Cluster Get Settings

The cluster get settings API allows to retrieve the cluster wide settings.

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

Or
[source,js]
--------------------------------------------------
GET /_cluster/settings?include_defaults=true
--------------------------------------------------
// CONSOLE

In the second example above, the parameter `include_defaults` ensures that the settings which were not set explicitly
are also returned. By default `include_defaults` is set to false.
Returns cluster-wide settings.

`GET /_cluster/settings`

[[cluster-get-settings-api-desc]]
==== {api-description-title}

By default, this API call only returns settings that have been explicitly
defined, but can also include the default settings by calling the
`include_defaults` parameter.


[[cluster-get-settings-api-query-params]]
==== {api-query-parms-title}


include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]

`include_defaults`::
(Optional, boolean) If `true`, returns all default cluster settings.
Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
95 changes: 59 additions & 36 deletions docs/reference/cluster/update-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,62 @@
[[cluster-update-settings]]
=== Cluster Update Settings

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

To review cluster settings:

[source,js]
--------------------------------------------------
GET /_cluster/settings
--------------------------------------------------
// CONSOLE
[[cluster-update-settings-api-request]]
==== {api-request-title}

`PUT /_cluster/settings`


[[cluster-update-settings-api-desc]]
==== {api-description-title}

With specifications in the request body, this API call can update cluster
settings. Updates to settings can be persistent, meaning they apply across
restarts, or transient, where they don't survive a full cluster restart.

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.

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 set all cluster-wide settings with the `settings` API and use the
`elasticsearch.yml` file only for local configurations. This way you can be sure that
the setting is the same on all nodes. If, on the other hand, you define different
settings on different nodes by accident using the configuration file, it is very
difficult to notice these discrepancies.

You can find the list of settings that you can dynamically update in
<<modules,Modules>>.


[[cluster-update-settings-api-query-params]]
==== {api-query-parms-title}

By default, this API call only returns settings that have been explicitly defined, but can also <<cluster-get-settings,include the default settings>>.
include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-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:
`include_defaults`::
(Optional, boolean) If `true`, returns all default cluster settings.
Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[cluster-update-settings-api-example]]
==== {api-examples-title}

An example of a persistent update:

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

This update is transient:

An example of a transient update:

[source,js]
--------------------------------------------------
Expand All @@ -40,7 +83,9 @@ PUT /_cluster/settings?flat_settings=true
--------------------------------------------------
// CONSOLE

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

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

[source,js]
--------------------------------------------------
Expand All @@ -54,12 +99,6 @@ The response to an update returns the changed setting, as in this response to th
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]

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:

Expand All @@ -74,6 +113,7 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE


The response does not include settings that have been reset:

[source,js]
Expand All @@ -86,6 +126,7 @@ The response does not include settings that have been reset:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]


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

Expand All @@ -100,21 +141,3 @@ PUT /_cluster/settings
--------------------------------------------------
// CONSOLE


[float]
==== 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 set all cluster-wide settings with the `settings` API and use the
`elasticsearch.yml` file only for local configurations. This way you can be sure that
the setting is the same on all nodes. If, on the other hand, you define different
settings on different nodes by accident using the configuration file, it is very
difficult to notice these discrepancies.

You can find the list of settings that you can dynamically update in <<modules,Modules>>.