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: