diff --git a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc index 66133c705cc49..3ee6ee0a38f4b 100644 --- a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc +++ b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc @@ -4,60 +4,59 @@ Nodes reload secure settings ++++ +Reloads the keystore on nodes in the cluster. -The cluster nodes reload secure settings API is used to re-load the keystore on each node. +[[cluster-nodes-reload-secure-settings-api-request]] +==== {api-request-title} -[source,console] --------------------------------------------------- -POST _nodes/reload_secure_settings -POST _nodes/nodeId1,nodeId2/reload_secure_settings --------------------------------------------------- -// TEST[setup:node] -// TEST[s/nodeId1,nodeId2/*/] +`POST _nodes/reload_secure_settings` + +`POST _nodes/>. +[[cluster-nodes-reload-secure-settings-api-desc]] +==== {api-description-title} -NOTE: {es} requires consistent secure settings across the cluster nodes, but this consistency is not enforced. -Hence, reloading specific nodes is not standard. It is only justifiable when retrying failed reload operations. +<> are stored in an on-disk keystore. Certain +of these settings are <>. That is, you +can change them on disk and reload them without restarting any nodes in the +cluster. When you have updated reloadable secure settings in your keystore, you +can use this API to reload those settings on each node. -==== Reload Password Protected Secure Settings +When the {es} keystore is password protected and not simply obfuscated, you must +provide the password for the keystore when you reload the secure settings. +Reloading the settings for the whole cluster assumes that all nodes' keystores +are protected with the same password; this method is allowed only when +<>. Alternatively, you can +reload the secure settings on each node by locally accessing the API and passing +the node-specific {es} keystore password. -When the {es} keystore is password protected and not simply obfuscated, the password for the keystore needs -to be provided in the request to reload the secure settings. -Reloading the settings for the whole cluster assumes that all nodes' keystores are protected with the same password -and is only allowed when {ref}/configuring-tls.html#tls-transport[node to node communications are encrypted] +[[cluster-nodes-reload-secure-settings-path-params]] +==== {api-path-parms-title} -[source,js] --------------------------------------------------- -POST _nodes/reload_secure_settings -{ - "reload_secure_settings": "s3cr3t" <1> -} --------------------------------------------------- -// NOTCONSOLE +``:: + (Optional, string) The names of particular nodes in the cluster to target. + For example, `nodeId1,nodeId2`. For node selection options, see + <>. + +NOTE: {es} requires consistent secure settings across the cluster nodes, but +this consistency is not enforced. Hence, reloading specific nodes is not +standard. It is justifiable only when retrying failed reload operations. -<1> The common password that the {es} keystore is encrypted with in every node of the cluster. +[[cluster-nodes-reload-secure-settings-api-request-body]] +==== {api-request-body-title} -Alternatively the secure settings can be reloaded on a per node basis, locally accessing the API and passing the -node-specific {es} keystore password. +`reload_secure_settings`:: + (Optional, string) The password for the {es} keystore. -[source,js] +[[cluster-nodes-reload-secure-settings-api-example]] +==== {api-examples-title} + +[source,console] -------------------------------------------------- -POST _nodes/_local/reload_secure_settings -{ - "reload_secure_settings": "s3cr3t" <1> -} +POST _nodes/reload_secure_settings +POST _nodes/nodeId1,nodeId2/reload_secure_settings -------------------------------------------------- -// NOTCONSOLE - -<1> The password that the {es} keystore is encrypted with on the local node. - - -[float] -[[rest-reload-secure-settings]] -==== REST Reload Secure Settings Response +// TEST[setup:node] +// TEST[s/nodeId1,nodeId2/*/] The response contains the `nodes` object, which is a map, keyed by the node id. Each value has the node `name` and an optional `reload_exception` @@ -82,3 +81,27 @@ that was thrown during the reload process, if any. -------------------------------------------------- // TESTRESPONSE[s/"my_cluster"/$body.cluster_name/] // TESTRESPONSE[s/"pQHNt5rXTTWNvUgOrdynKg"/\$node_name/] + +The following example uses a common password for the {es} keystore on every +node of the cluster: + +[source,js] +-------------------------------------------------- +POST _nodes/reload_secure_settings +{ + "reload_secure_settings": "s3cr3t" +} +-------------------------------------------------- +// NOTCONSOLE + +The following example uses a password for the {es} keystore on the local node: + +[source,js] +-------------------------------------------------- +POST _nodes/_local/reload_secure_settings +{ + "reload_secure_settings": "s3cr3t" +} +-------------------------------------------------- +// NOTCONSOLE + diff --git a/docs/reference/setup/secure-settings.asciidoc b/docs/reference/setup/secure-settings.asciidoc index 7f0a99e21389d..233878041231a 100644 --- a/docs/reference/setup/secure-settings.asciidoc +++ b/docs/reference/setup/secure-settings.asciidoc @@ -25,7 +25,7 @@ are node-specific settings that must have the same value on every node. Just like the settings values in `elasticsearch.yml`, changes to the keystore contents are not automatically applied to the running {es} node. Re-reading settings requires a node restart. However, certain secure settings are marked as -*reloadable*. Such settings can be re-read and applied on a running node. +*reloadable*. Such settings can be <>. The values of all secure settings, *reloadable* or not, must be identical across all cluster nodes. After making the desired secure settings changes, @@ -50,8 +50,8 @@ dependent on these settings have been changed. Everything should look as if the settings had the new value from the start. When changing multiple *reloadable* secure settings, modify all of them on each -cluster node, then issue a `reload_secure_settings` call instead of reloading -after each modification. +cluster node, then issue a <> +call instead of reloading after each modification. There are reloadable secure settings for: