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

Use standard format for reload settings API #51560

Merged
merged 6 commits into from
Feb 3, 2020
Merged

Use standard format for reload settings API #51560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a90c3a9
Use standard format for reload settings API
williamrandolph Jan 28, 2020
d75c3f3
Fix broken links
williamrandolph Jan 28, 2020
64a4883
Reorder examples to correctly check API response
williamrandolph Jan 28, 2020
56ef82d
Note that only certain settings are reloadable
williamrandolph Jan 29, 2020
3fdbf0d
[DOCS] Edits layout
lcawl Jan 31, 2020
8af02b6
[DOCS] Removes unnecessary callouts
lcawl Jan 31, 2020
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
107 changes: 65 additions & 42 deletions docs/reference/cluster/nodes-reload-secure-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,60 +4,59 @@
<titleabbrev>Nodes reload secure settings</titleabbrev>
++++

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/<nodes/reload_secure_settings`

The first command reloads the keystore on each node. The seconds allows
to selectively target `nodeId1` and `nodeId2`. The node selection options are
detailed <<cluster-nodes,here>>.
[[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.
<<secure-settings,Secure settings>> are stored in an on-disk keystore. Certain
of these settings are <<reloadable-secure-settings,reloadable>>. 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
<<tls-transport,inter-node communications are encrypted>>. 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
`<nodes>`::
(Optional, string) The names of particular nodes in the cluster to target.
For example, `nodeId1,nodeId2`. For node selection options, see
<<cluster-nodes>>.
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`
Expand All @@ -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

6 changes: 3 additions & 3 deletions docs/reference/setup/secure-settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<cluster-nodes-reload-secure-settings, re-read and applied on a running node>>.

The values of all secure settings, *reloadable* or not, must be identical
across all cluster nodes. After making the desired secure settings changes,
Expand All @@ -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 <<cluster-nodes-reload-secure-settings, `reload_secure_settings`>>
call instead of reloading after each modification.

There are reloadable secure settings for:

Expand Down