Use standard format for reload settings API (elastic#51560) (elastic#…

…51828) * Use standard format for reload settings API The reload-secure-settings API page was not reorganized for the standard API format, so this commit is reorganizing the page and adding some links to the page in related documentation. * Fix broken links * Reorder examples to correctly check API response * Note that only certain settings are reloadable * [DOCS] Edits layout * [DOCS] Removes unnecessary callouts Co-authored-by: Lisa Cawley <lcawley@elastic.co> Co-authored-by: Lisa Cawley <lcawley@elastic.co>
jtibshirani · Feb 3, 2020 · ba2810f · ba2810f
1 parent d293980
commit ba2810f
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 45 deletions.
diff --git a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc
@@ -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`
@@ -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
@@ -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,
@@ -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: