Node repurpose tool docs #40525

henningandersen · 2019-03-27T13:34:05Z

Added documentation for node repurpose tool.

Follow-up to #39403

Added documentation for node repurpose tool.

elasticmachine · 2019-03-27T13:34:07Z

Pinging @elastic/es-distributed

andrershov

As I mentioned earlier, there would be problems with combining documentation for unsafe-bootstrap/detach-cluster and repurpose. For example, when reading the description section there are several paragraphs that talk about unsafe cluster recover, but after that, there is a paragraph about repurpose and just one question arises - what is it all about?
I still think that the best idea is to explicitly have elasticsearch-repurpose tool separately.
But if we don't want to do it, we need to think carefully about grouping description/examples in such a way that do not confuse the reader.
The only idea that comes to my mind is to make too child pages for elasticsearch-node tool - one for unsafe-bootstrap/detach-cluster and another for repurpose. On the parent page, we can leave short general description and synopsis, but everything else comes to separate pages. But still, it looks artificial.
@ywelsch @DaveCTurner do you have better ideas?

henningandersen · 2019-03-28T18:25:05Z

Thanks for looking into this @andrershov . I tend to think the tool is quite coherent in that all 3 commands relate to the node's role in the cluster and tries to avoid someone messing directly with files in the data path.
I could probably make that clearer in the documentation, but I was feeling a little constrained by not wanting to rewrite the entire Description section since you all spent a good deal of time ensuring the correctness of it, paying attention to many details in the original node-tool docs PR #37812.
Just my cents, will await feedback from @ywelsch and @DaveCTurner .

andrershov

@henningandersen By intro I mean the paragraph that is already in the documentation

The `elasticsearch-node` command enables you to perform unsafe operations that
risk data loss but which may help to recover some data in a disaster.

This and synopsis can stay in the parent page - everything else will go to the child pages. And child page for unsafe-bootstrap/detach-cluster will look the same way it was before your changes. All your additions will go to the corresponding sections of repurpose child page.

henningandersen · 2019-03-29T12:49:15Z

@andrershov by intro section, I really meant the Description section, I have updated my comment above to clarify that.

DaveCTurner

I'm inclined to agree with @andrershov that this change makes these docs feel a bit disjointed. See also this comment with which I agree: eventually I think we want to move the conceptual overview of these things to a place that isn't buried so deeply. I do not think we should split the docs for each sub-command out into separate pages, although it's possible we would want to do this for the conceptual overview.

Yet I think it's important we have this tool documented here for now, and we can defer this larger refactoring until later.

I left some suggestions, mostly about structure/order, and also noted that I think there's something missing on the subject from docs/reference/modules/node.asciidoc.

DaveCTurner · 2019-03-29T12:34:11Z

docs/reference/commands/node-tool.asciidoc

@@ -2,14 +2,15 @@
 == elasticsearch-node

 The `elasticsearch-node` command enables you to perform unsafe operations that
-risk data loss but which may help to recover some data in a disaster.
+risk data loss but which may help to recover some data in a disaster and
+repurpose nodes into new roles.


Suggest breaking into two simpler sentences:

The `elasticsearch-node` command enables you to perform certain unsafe operations on a node that are only possible while it is shut down. This command allows you to adjust the <<modules-node,role>> of a node and may be able to recover some data after a disaster.

Which reminds me, the docs about roles are at docs/reference/modules/node.asciidoc and I think we should have docs there to say that you now have to take special steps to change the role of a node.

DaveCTurner · 2019-03-29T12:35:42Z

docs/reference/commands/node-tool.asciidoc


 [float]
 === Synopsis

 [source,shell]
 --------------------------------------------------
-bin/elasticsearch-node unsafe-bootstrap|detach-cluster
+bin/elasticsearch-node unsafe-bootstrap|detach-cluster|repurpose


I'm inclined to put the repurpose command first here (and elsewhere) because of the three commands it's the one that we hope is the most used.

DaveCTurner · 2019-03-29T12:38:28Z

docs/reference/commands/node-tool.asciidoc

@@ -53,19 +54,28 @@ way forward that does not risk data loss, but it may be possible to use the
 `elasticsearch-node` tool to construct a new cluster that contains some of the
 data from the failed cluster.

-This tool has two modes:
+If a node that previously held data or were master-eligible is repurposed into


I suggest:

moving this to the top of the Description section,

making new subheadings e.g. ==== Changing the roles of a node and ==== Recovering data after a disaster to separate the sections more clearly, and

expanding this paragraph into a longer description of the concepts (and/or describing the concepts in docs/reference/modules/node.asciidoc and linking to them).

About item 3: I think master-eligible node and data node are already described in docs/reference/modules/node.asciidoc. I can certainly link to those descriptions. But it sounds like you wanted something more than that, can you elaborate on that?

Sure, sorry, I'll clarify. Today the Node docs describe the node.data and node.master settings but do not say anything about how to go about changing them. This makes sense in 6.x because you don't have to do anything particularly special to change them, but in 7.0 this is no longer the case. I think that page needs to mention that you should only really set these settings before starting a node for the first time, and also talk about (or at least link to) the extra steps you need to do if you want to change them later.

DaveCTurner · 2019-03-29T12:38:33Z

docs/reference/commands/node-tool.asciidoc

  remaining master-eligible node. It forces one of the remaining nodes to form
  a brand-new cluster on its own, using its local copy of the cluster metadata.
  This is known as _unsafe cluster bootstrapping_.

-* `elastisearch-node detach-cluster` enables you to move nodes from one cluster
+* `elasticsearch-node detach-cluster` enables you to move nodes from one cluster


DaveCTurner · 2019-03-29T12:38:43Z

docs/reference/commands/node-tool.asciidoc

  to another. This can be used to move nodes into the new cluster created with
  the `elastisearch-node unsafe-bootstap` command. If unsafe cluster bootstrapping was not
  possible, it also enables you to
  move nodes into a brand-new cluster.

+* `elasticsearch-node repurpose` reports on and performs necessary index meta-data


I'd put this mode first.

DaveCTurner · 2019-03-29T12:39:14Z

docs/reference/commands/node-tool.asciidoc

@@ -206,6 +216,44 @@ The message `Node was successfully detached from the cluster` does not mean
 that there has been no data loss, it just means that tool was able to complete
 its job.

+
+[[node-tool-repurpose]]


I'd put this section above the other two.

DaveCTurner · 2019-03-29T12:50:15Z

docs/reference/commands/node-tool.asciidoc

+[float]
+==== Repurposing nodes
+
+A master-eligible and data carrying node holds on-disk index data:


I think I'd prefer to try and split this whole section into two parallel descriptions about node.data and node.master respectively, because here it's a bit unclear what this says about a master-ineligible data node or (conversely) a dedicated master node. It might be a little repetitive, but I'm ok with that.

DaveCTurner · 2019-03-29T12:51:32Z

docs/reference/commands/node-tool.asciidoc

@@ -215,6 +263,8 @@ one-node cluster.
 `detach-cluster`:: Specifies to unsafely detach this node from its cluster so
 it can join a different cluster.

+`repurpose`:: Report on and cleanup excess persisted data.


I'd put this first.

DaveCTurner · 2019-03-29T12:51:36Z

docs/reference/commands/node-tool.asciidoc

@@ -332,3 +382,45 @@ Confirm [y/N] y
 Node was successfully detached from the cluster
 ----

+[float]
+==== Repurposing node as master, no-data


I'd put this first.

henningandersen · 2019-03-29T16:35:38Z

Thanks @andrershov and @DaveCTurner for your reviews. I tried to adhere to all comments in one commit: 3879859bafcada9cc42ad56095b7c673dc8e0e02 (felt unnatural to split into multiple commits). I did not split the page, but went for two subsections in the Description section.

Please have another look.

Improved documentation for node repurpose tool.

DaveCTurner

I left a few more nits but the structure feels good to me now. I would like to do a bit of wordsmithery with the longer sections of words but will defer that until after the weekend.

DaveCTurner · 2019-03-29T17:05:07Z

docs/reference/commands/node-tool.asciidoc

@@ -230,6 +284,49 @@ to `0`, meaning to use the first node in the data path.
 [float]
 === Examples

+[float]
+==== Repurposing node as master, no-data


Suggested change

==== Repurposing node as master, no-data

==== Repurposing a data node as a dedicated master node

DaveCTurner · 2019-03-29T17:06:16Z

docs/reference/commands/node-tool.asciidoc

+----
+
+[float]
+==== Repurposing node as no-master, no-data


Suggested change

==== Repurposing node as no-master, no-data

==== Repurposing a data node as a coordinating-only node

DaveCTurner · 2019-03-29T17:09:48Z

docs/reference/commands/node-tool.asciidoc

+[float]
+==== Repurposing node as no-master, no-data
+
+In this example, a node that previously held data is repurposed as no-master, no-data.


Suggested change

In this example, a node that previously held data is repurposed as no-master, no-data.

In this example, a node that previously held data is repurposed as a coordinating-only node.

docs/reference/commands/node-tool.asciidoc

DaveCTurner · 2019-03-29T17:11:01Z

docs/reference/commands/node-tool.asciidoc

+[float]
+==== Repurposing node as master, no-data
+
+In this example, a node that previously held data is repurposed as master, no-data.


Suggested change

In this example, a node that previously held data is repurposed as master, no-data.

In this example, a node that previously held data is repurposed as a dedicated master node.

docs/reference/commands/node-tool.asciidoc

Clarifty that changes happen in .yml file. Co-Authored-By: henningandersen <[email protected]>

Clarify that changes happen in .yml file. Co-Authored-By: henningandersen <[email protected]>

Changed terminology a bit to use coordinating-only and dedicated master. Though not entirely true, it gives a slightly easier read.

henningandersen · 2019-03-31T18:35:34Z

Thanks @DaveCTurner , I have addressed the 4 changes, though not identically to what you requested. Let me know if you have additional comments.

…ose_tool_docs

henningandersen · 2019-04-08T09:43:38Z

@elasticmachine run elasticsearch-ci/1

DaveCTurner · 2019-04-08T15:10:42Z

@henningandersen I have done a bit of work on this on my own branch (on top of this one): master...DaveCTurner:2019-04-08-feature_node_repurpose_tool_docs

I added more detail about repurposing to the Node page which simplified the tool docs a bit. Could you compare and bring in any changes you like?

Comments all addressed, but more changes incoming...

Removed todo and changed metadata to data to also capture shard data.

henningandersen · 2019-04-09T08:16:46Z

I added more detail about repurposing to the Node page which simplified the tool docs a bit. Could you compare and bring in any changes you like?

Thanks @DaveCTurner , I took your changes as is and made two small changes only in 514831d

DaveCTurner

LGTM

…ose_tool_docs

andrershov

LGTM2

henningandersen · 2019-04-09T12:54:31Z

Thanks @DaveCTurner and @andrershov

Added documentation for node repurpose tool and included documentation on how to repurpose nodes safely. Adjusted order of tools in `elasticsearch-node` tool since the repurpose tool is most likely to be used. Co-Authored-By: David Turner <[email protected]>

…forced-unsafe-publication * elastic/master: Improve Watcher test framework resiliency (elastic#40658) Fix order of request body search parameter names in documentation (elastic#40777) Node repurpose tool docs (elastic#40525) [Docs] Delete explanation for completion suggester default analyzer choice (elastic#36720) Revert "Revert "Change HLRC CCR response tests to use AbstractResponseTestCase base class. (elastic#40257)"" (elastic#40971) Short-circuit rebalancing when disabled (elastic#40966)

Added documentation for node repurpose tool and included documentation on how to repurpose nodes safely. Adjusted order of tools in `elasticsearch-node` tool since the repurpose tool is most likely to be used. Co-Authored-By: David Turner <[email protected]>

Node repurpose tool docs

02dd1d3

Added documentation for node repurpose tool.

henningandersen added >docs General docs changes v7.0.0 :Distributed Coordination/Allocation All issues relating to the decision making around placing a shard (both master logic & on the nodes) v8.0.0 v7.2.0 labels Mar 27, 2019

henningandersen requested a review from andrershov March 27, 2019 13:34

andrershov suggested changes Mar 28, 2019

View reviewed changes

andrershov reviewed Mar 29, 2019

View reviewed changes

DaveCTurner previously requested changes Mar 29, 2019

View reviewed changes

Node repurpose tool docs

a09c826

Improved documentation for node repurpose tool.

henningandersen force-pushed the feature_node_repurpose_tool_docs branch from 3879859 to a09c826 Compare March 29, 2019 17:01

DaveCTurner reviewed Mar 29, 2019

View reviewed changes

DaveCTurner and others added 3 commits March 31, 2019 20:26

Node repurpose tool docs

cda16db

Clarifty that changes happen in .yml file. Co-Authored-By: henningandersen <[email protected]>

Node repurpose tool docs

4d37e79

Clarify that changes happen in .yml file. Co-Authored-By: henningandersen <[email protected]>

Node repurpose tool docs

57511a5

Changed terminology a bit to use coordinating-only and dedicated master. Though not entirely true, it gives a slightly easier read.

Merge remote-tracking branch 'origin/master' into feature_node_repurp…

d040a30

…ose_tool_docs

DaveCTurner and others added 2 commits April 9, 2019 10:03

Rewording

7fefa44

Node repurpose tool docs

514831d

Removed todo and changed metadata to data to also capture shard data.

henningandersen requested review from DaveCTurner and andrershov April 9, 2019 08:19

DaveCTurner approved these changes Apr 9, 2019

View reviewed changes

Merge remote-tracking branch 'origin/master' into feature_node_repurp…

ad9c814

…ose_tool_docs

andrershov approved these changes Apr 9, 2019

View reviewed changes

henningandersen merged commit 0783efd into elastic:master Apr 9, 2019

$@polyfractal$ polyfractal added v7.0.1 and removed v7.0.0 labels Apr 9, 2019

jakelandis added v8.0.0-alpha1 and removed v8.0.0 labels Jul 26, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Node repurpose tool docs #40525

Node repurpose tool docs #40525

henningandersen commented Mar 27, 2019

elasticmachine commented Mar 27, 2019

andrershov left a comment

henningandersen commented Mar 28, 2019 •

edited

Loading

andrershov left a comment •

edited

Loading

henningandersen commented Mar 29, 2019

DaveCTurner left a comment

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

henningandersen Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

henningandersen commented Mar 29, 2019

DaveCTurner left a comment

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

DaveCTurner Mar 29, 2019

henningandersen commented Mar 31, 2019

henningandersen commented Apr 8, 2019

DaveCTurner commented Apr 8, 2019

henningandersen commented Apr 9, 2019

DaveCTurner left a comment

andrershov left a comment

henningandersen commented Apr 9, 2019

	==== Repurposing node as master, no-data
	==== Repurposing a data node as a dedicated master node

	==== Repurposing node as no-master, no-data
	==== Repurposing a data node as a coordinating-only node

	In this example, a node that previously held data is repurposed as no-master, no-data.
	In this example, a node that previously held data is repurposed as a coordinating-only node.

Node repurpose tool docs #40525

Node repurpose tool docs #40525

Conversation

henningandersen commented Mar 27, 2019

elasticmachine commented Mar 27, 2019

andrershov left a comment

Choose a reason for hiding this comment

henningandersen commented Mar 28, 2019 • edited Loading

andrershov left a comment • edited Loading

Choose a reason for hiding this comment

henningandersen commented Mar 29, 2019

DaveCTurner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henningandersen commented Mar 29, 2019

DaveCTurner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henningandersen commented Mar 31, 2019

henningandersen commented Apr 8, 2019

DaveCTurner commented Apr 8, 2019

henningandersen commented Apr 9, 2019

DaveCTurner left a comment

Choose a reason for hiding this comment

andrershov left a comment

Choose a reason for hiding this comment

henningandersen commented Apr 9, 2019

henningandersen commented Mar 28, 2019 •

edited

Loading

andrershov left a comment •

edited

Loading