From 46866749b08868cab77a04aa0c540cab3df2db14 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Mon, 20 Aug 2018 18:34:53 +0300 Subject: [PATCH 1/3] REST spec and docs for the reload secure settings REST handle --- .../nodes-reload-secure-settings.asciidoc | 57 +++++++++++++++++++ .../api/nodes.reload_secure_settings.json | 23 ++++++++ .../nodes.reload_secure_settings/10_basic.yml | 8 +++ 3 files changed, 88 insertions(+) create mode 100644 docs/reference/cluster/nodes-reload-secure-settings.asciidoc create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/api/nodes.reload_secure_settings.json create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/test/nodes.reload_secure_settings/10_basic.yml diff --git a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc new file mode 100644 index 0000000000000..d57a13da53c99 --- /dev/null +++ b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc @@ -0,0 +1,57 @@ +[[cluster-nodes-reload-secure-settings]] +== Nodes Reload Secure Settings + +The cluster nodes reload secure settings API is used to re-read the +local node's encrypted keystore. Specifically, it broadcasts a password +which is used to decrypt the contents of the node's keystore. The keystore's +plain content is then used to reinitialize compatible plugins. The operation is +complete when all compatible plugins have finished reinitilizing. Subsequently, +the keystore is closed and any modifications will not be reflected by plugins. + +Note: At the moment, the password parameter is not supported. The empty password +is the only valid value. Consequently, the request body is empty. + +[source,js] +-------------------------------------------------- +POST _nodes/reload_secure_settings +POST _nodes/nodeId1,nodeId2/reload_secure_settings +-------------------------------------------------- +// CONSOLE +// TEST[setup:node] +// TEST[s/nodeId1,nodeId2/*/] + +The first command reloads the keystore on each node. The seconds allows +to selectively target `nodeId1` and `nodeId2`. The node selection options are +detailed <>. + +Note: It is an error if secure settings are inconsistent across the cluster +nodes, yet consistency is not enforced whatsoever. Hence, reloading specific +nodes is not standard. It is only justifiable when retrying failed reload operations. + +[float] +[[rest-reload-secure-settings]] +==== REST Reload Secure Settings Response + +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` +field. The `reload_exception` field is a serialization of the exception +that was thrown during the reload process, if any. + +[source,js] +-------------------------------------------------- +{ + "_nodes": { + "total": 1, + "successful": 1, + "failed": 0 + }, + "cluster_name": "my_cluster", + "nodes": { + "pQHNt5rXTTWNvUgOrdynKg": { + "name": "node-0" + } + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"my_cluster"/$body.cluster_name/] +// TESTRESPONSE[s/"pQHNt5rXTTWNvUgOrdynKg"/\$node_name/] diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/nodes.reload_secure_settings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/nodes.reload_secure_settings.json new file mode 100644 index 0000000000000..487beaba86520 --- /dev/null +++ b/rest-api-spec/src/main/resources/rest-api-spec/api/nodes.reload_secure_settings.json @@ -0,0 +1,23 @@ +{ + "nodes.reload_secure_settings": { + "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-reload-secure-settings.html", + "methods": ["POST"], + "url": { + "path": "/_nodes/reload_secure_settings", + "paths": ["/_nodes/reload_secure_settings", "/_nodes/{node_id}/reload_secure_settings"], + "parts": { + "node_id": { + "type": "list", + "description": "A comma-separated list of node IDs to span the reload/reinit call. Should stay empty because reloading usually involves all cluster nodes." + } + }, + "params": { + "timeout": { + "type" : "time", + "description" : "Explicit operation timeout" + } + } + }, + "body": null + } +} diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/nodes.reload_secure_settings/10_basic.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/nodes.reload_secure_settings/10_basic.yml new file mode 100644 index 0000000000000..0a4cf0d64a001 --- /dev/null +++ b/rest-api-spec/src/main/resources/rest-api-spec/test/nodes.reload_secure_settings/10_basic.yml @@ -0,0 +1,8 @@ +--- +"node_reload_secure_settings test": + + - do: + nodes.reload_secure_settings: {} + + - is_true: nodes + - is_true: cluster_name From ce6bab6cde1a0066950f210eed656302c3c987a9 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Tue, 21 Aug 2018 14:59:07 +0300 Subject: [PATCH 2/3] reload secure settings API is not required for HLREST feature completion --- .../java/org/elasticsearch/client/RestHighLevelClientTests.java | 1 + 1 file changed, 1 insertion(+) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java index b5d8dbb628eb9..76b18b5112aa3 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java @@ -685,6 +685,7 @@ public void testApiNamingConventions() throws Exception { "nodes.stats", "nodes.hot_threads", "nodes.usage", + "nodes.reload_secure_settings", "search_shards", }; Set deprecatedMethods = new HashSet<>(); From 3516eda513d0e2cf0b1fdc96c825e901c3f53ca7 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Tue, 21 Aug 2018 15:35:40 +0300 Subject: [PATCH 3/3] docs: banish any limiting password mention --- .../cluster/nodes-reload-secure-settings.asciidoc | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc index d57a13da53c99..f02ac8e46576b 100644 --- a/docs/reference/cluster/nodes-reload-secure-settings.asciidoc +++ b/docs/reference/cluster/nodes-reload-secure-settings.asciidoc @@ -2,14 +2,12 @@ == Nodes Reload Secure Settings The cluster nodes reload secure settings API is used to re-read the -local node's encrypted keystore. Specifically, it broadcasts a password -which is used to decrypt the contents of the node's keystore. The keystore's -plain content is then used to reinitialize compatible plugins. The operation is +local node's encrypted keystore. Specifically, it will prompt the keystore +decryption and reading accross the cluster. The keystore's plain content is +used to reinitialize all compatible plugins. A compatible plugin can be +reinitilized without restarting the node. The operation is complete when all compatible plugins have finished reinitilizing. Subsequently, -the keystore is closed and any modifications will not be reflected by plugins. - -Note: At the moment, the password parameter is not supported. The empty password -is the only valid value. Consequently, the request body is empty. +the keystore is closed and any changes to it will not be reflected on the node. [source,js] -------------------------------------------------- @@ -25,7 +23,7 @@ to selectively target `nodeId1` and `nodeId2`. The node selection options are detailed <>. Note: It is an error if secure settings are inconsistent across the cluster -nodes, yet consistency is not enforced whatsoever. Hence, reloading specific +nodes, yet this consistency is not enforced whatsoever. Hence, reloading specific nodes is not standard. It is only justifiable when retrying failed reload operations. [float]