Add elasticsearch-node tool docs #37812
Conversation
andrershov
added
>docs
|
Pinging @elastic/es-distributed |
| <<path-settings,`path.data` setting>>. This means that in a disaster you can | ||
| also restart a node by moving its data directories to another host, presuming | ||
| that those data directories can be recovered from the faulty host. Note that it | ||
| is not possible to restore the data directory from a backup because this will |
There was a problem hiding this comment.
@DaveCTurner Not sure what you mean by "is not possible to restore the data directory from a backup".
If you copy full data folder to another node, this node will be indistinguishable from the previous node.
There was a problem hiding this comment.
Copying the literal data directory of the dead node somewhere else, post-mortem, is ok, but restoring from a backup (which could be who-knows-how stale) is decidedly not. We occasionally see people taking backups of their data directories and causing hassle when they discover that they can't restore from such things, and I saw a risk that this paragraph might be interpreted wrongly by those kinds of people.
There was a problem hiding this comment.
@DaveCTurner Now I see what you mean, can we re-phrase it like "Note that if you have previously taken a backup of the data folder of the stopped node, you can not restore from it, you need a data folder state at the moment this node was stopped"
There was a problem hiding this comment.
The trouble with the phrase "if you have previously taken a backup of the data folder" is that it suggests this is a thing you might try and do, and I think we should avoid making that suggestion. Technically you can't take a backup of the data folder: a backup from which you cannot ever safely restore isn't really a backup at all 🤔.
There was a problem hiding this comment.
@DaveCTurner I agree. In this case, probably it makes sense to remove this sentence at all because it's confusing?
Also, the better place for explaining that there is no reason to copy data folders because it's not possible to restore from them is on the snapshot page.
|
@DaveCTurner thanks for your re-work! I've left one question and pushed one commit, that adds (term, version) instructions and updates sample run. |
|
I was also thinking of a |
|
@elasticmachine please run elasticsearch-ci/oss-distro-docs |
elasticsearch-node tool helps to restore cluster if half or more of master eligible nodes are lost. Of course, all bets are off, regarding data consistency. There are two parts of the tool: unsafe-bootstrap to be used when there is still at least one master-eligible node alive and detach-cluster, when there are no master-eligible nodes left. This commit implements the first part. Docs for the tool will be added separately as a part of #37812.
…ing the node itself
|
I looked at this with a fresh set of eyes this morning and tidied up a couple of things that stood out to me. I would also like Lisa to review (or to delegate to someone else on the docs team). |
There was a problem hiding this comment.
@DaveCTurner I still think we need to re-phrase the part about data folder backup, other than that looks good to me.
| <<path-settings,`path.data` setting>>. This means that in a disaster you can | ||
| also restart a node by moving its data directories to another host, presuming | ||
| that those data directories can be recovered from the faulty host. Note that it | ||
| is not possible to restore the data directory from a backup because this will |
There was a problem hiding this comment.
@DaveCTurner Now I see what you mean, can we re-phrase it like "Note that if you have previously taken a backup of the data folder of the stopped node, you can not restore from it, you need a data folder state at the moment this node was stopped"
|
Andrey rightly points out that we've not finished the other half of this tool, or its docs, so my request for review from the docs team was premature. Sorry for the noise. |
|
One thing I'd suggest adding is the Synopsis section that lists all the options, per https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-passwords.html |
# Conflicts: # docs/reference/commands/node-tool.asciidoc
|
@DaveCTurner I've added |
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
Co-Authored-By: andrershov <[email protected]>
This commit, mostly authored by @DaveCTurner, adds documentation for elasticsearch-node tool #37696. (cherry picked from commit 09425d5)
This commit, mostly authored by @DaveCTurner, adds documentation for elasticsearch-node tool #37696. (cherry picked from commit 09425d5)
This PR adds documentation for elasticsearch-node tool #37696.