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 3 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
51 changes: 36 additions & 15 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,31 +4,44 @@
<titleabbrev>Nodes reload secure settings</titleabbrev>
++++


The cluster nodes reload secure settings API is used to re-load the keystore on each node.

[source,console]
--------------------------------------------------
POST _nodes/reload_secure_settings
POST _nodes/nodeId1,nodeId2/reload_secure_settings
--------------------------------------------------
// TEST[setup:node]
// TEST[s/nodeId1,nodeId2/*/]
[[cluster-nodes-reload-secure-settings-api-request]]
==== {api-request-title}
`POST _nodes/reload_secure_settings` +

`POST _nodes/nodeId1,nodeId2/reload_secure_settings` +
Copy link
Contributor

Choose a reason for hiding this comment

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

This should line up with the path parameter section:

Suggested change
`POST _nodes/nodeId1,nodeId2/reload_secure_settings` +
`POST _nodes/<nodes>/reload_secure_settings` +


`POST _nodes/_local/reload_secure_settings`
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this can be omitted since it's just another example of a value and it's mentioned in the link from the path parameters section.


[[cluster-nodes-reload-secure-settings-api-desc]]
==== {api-description-title}
Secure settings are stored in an on-disk keystore. When you have updated
the secure settings in your keystore, you can use this API to reload those
williamrandolph marked this conversation as resolved.
Show resolved Hide resolved
settings on each node. You may also selectively target `nodeId1` and
`nodeId2`. The node selection options are detailed <<cluster-nodes,here>>.

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-path-params]]
==== {api-path-parms-title}

`<nodes>`::
(Optional, string) The names of particular nodes in the cluster to target.
May also be `_local` to reload settings on just the local node.

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.

==== Reload Password Protected Secure Settings
[[cluster-nodes-reload-secure-settings-api-request-body]]
==== {api-request-body-title}

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]

`reload_secure_settings`::
(Optional, string) The password for the Elasticsearch keystore.

[source,js]
--------------------------------------------------
POST _nodes/reload_secure_settings
Expand All @@ -54,10 +67,18 @@ POST _nodes/_local/reload_secure_settings

<1> The password that the {es} keystore is encrypted with on the local node.

[[cluster-nodes-reload-secure-settings-api-example]]
==== {api-examples-title}

Rest example:

[float]
[[rest-reload-secure-settings]]
==== REST Reload Secure Settings Response
[source,console]
--------------------------------------------------
POST _nodes/reload_secure_settings
POST _nodes/nodeId1,nodeId2/reload_secure_settings
--------------------------------------------------
// 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 Down
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