From a6beac74e2c095eafca8cc4da0effc9d89cd6c16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 8 Aug 2019 16:43:57 +0200 Subject: [PATCH 1/2] [DOCS] Reformats cluster update API. --- .../cluster/update-settings.asciidoc | 97 ++++++++++++------- 1 file changed, 61 insertions(+), 36 deletions(-) diff --git a/docs/reference/cluster/update-settings.asciidoc b/docs/reference/cluster/update-settings.asciidoc index ae5f3c2f7b75c..13ce89165aba7 100644 --- a/docs/reference/cluster/update-settings.asciidoc +++ b/docs/reference/cluster/update-settings.asciidoc @@ -1,20 +1,64 @@ [[cluster-update-settings]] === Cluster Update Settings -Use this API to review and change cluster-wide settings. +Returns and changes cluster-wide settings. -To review cluster settings: -[source,js] --------------------------------------------------- -GET /_cluster/settings --------------------------------------------------- -// CONSOLE +[[cluster-update-settings-api-request]] +==== {api-request-title} + +`GET /_cluster/settings` + + +[[cluster-update-settings-api-desc]] +==== {api-description-title} + +By default, this API call only returns settings that have been explicitly +defined, but can also <>. + +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 +<>. + -By default, this API call only returns settings that have been explicitly defined, but can also <>. +[[cluster-update-settings-api-query-params]] +==== {api-query-parms-title} -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::{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] + + +[[cluster-update-settings-api-example]] +==== {api-examples-title} + +An example of a persistent update: [source,js] -------------------------------------------------- @@ -27,7 +71,8 @@ PUT /_cluster/settings -------------------------------------------------- // CONSOLE -This update is transient: + +An example of a transient update: [source,js] -------------------------------------------------- @@ -40,7 +85,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] -------------------------------------------------- @@ -54,12 +101,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: @@ -74,6 +115,7 @@ PUT /_cluster/settings -------------------------------------------------- // CONSOLE + The response does not include settings that have been reset: [source,js] @@ -86,6 +128,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: @@ -100,21 +143,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 <>. - From e6f59dd5d49c8949e39d42d203ba018766a93993 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 12 Aug 2019 10:17:46 +0200 Subject: [PATCH 2/2] Splits GET and PUT cluster settings APIs. --- docs/reference/cluster/get-settings.asciidoc | 40 +++++++++++-------- .../cluster/update-settings.asciidoc | 12 +++--- 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/docs/reference/cluster/get-settings.asciidoc b/docs/reference/cluster/get-settings.asciidoc index ac5df7b7aa876..32661bdaf462a 100644 --- a/docs/reference/cluster/get-settings.asciidoc +++ b/docs/reference/cluster/get-settings.asciidoc @@ -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. \ No newline at end of file +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] \ No newline at end of file diff --git a/docs/reference/cluster/update-settings.asciidoc b/docs/reference/cluster/update-settings.asciidoc index 13ce89165aba7..e2da6c5161763 100644 --- a/docs/reference/cluster/update-settings.asciidoc +++ b/docs/reference/cluster/update-settings.asciidoc @@ -1,23 +1,21 @@ [[cluster-update-settings]] === Cluster Update Settings -Returns and changes cluster-wide settings. +Updates cluster-wide settings. [[cluster-update-settings-api-request]] ==== {api-request-title} -`GET /_cluster/settings` +`PUT /_cluster/settings` [[cluster-update-settings-api-desc]] ==== {api-description-title} -By default, this API call only returns settings that have been explicitly -defined, but can also <>. - -Updates to settings can be persistent, meaning they apply across restarts, or -transient, where they don't survive a full cluster restart. +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