Document ballast file as production best practice #5000
Conversation
|
This change is |
There was a problem hiding this comment.
Reviewed 16 of 16 files at r1.
Reviewable status:complete! 0 of 0 LGTMs obtained (waiting on @jseldess)
v19.1/debug-ballast.md, line 7 at r1 (raw file):
--- The `debug ballast` [command](cockroach-commands.html) creates a large, unused file that you can place in a node's storage directory. In the unlikely case that a node runs out of disk space and shuts down, you can delete the ballast file to free up enough space to be able to restart the node.
Consider adding a footnote like "Ballast files may be created in many ways, including the standard dd command. cockroach debug ballast uses the fallocate system call when available so it will be faster than dd."
v19.1/debug-ballast.md, line 39 at r1 (raw file):
{% include copy-clipboard.html %} ~~~ shell $ cockroach debug ballast cockroach-data/ballast.txt --size=20GiB
20GiB is a lot. I think 1GiB is generally sufficient. (In addition to moving this out of debug we should probably give it a default. There's no reason to make people choose a value here)
v19.1/debug-encryption-active-key.md, line 11 at r1 (raw file):
## Subcommands While the `cockroach debug` command has a few subcommands, users are expected to use only the [`zip`](debug-zip.html), [`encryption-active-key`](debug-encryption-active-key.html), [`merge-logs`](debug-merge-logs.html), and [`ballast`](debug-ballast.html) subcommands.
We shouldn't repeat this list on every debug subcommand. Just make a page for cockroach debug for this.
Also as we identify debug commands that are worth documenting, we should consider moving them out of debug.
v19.1/operational-faqs.md, line 100 at r1 (raw file):
## What happens when a node runs out of disk space? When a node runs out of disk space, it shuts down and cannot be restarted until space is freed up. To prepare for this unlikely case, place a [ballast file](debug-ballast.html) in each node's storage directory that can be deleted to free up enough space to be able to restart the node.
Add something like "If you did not create a ballast file, look for other files that can be deleted, such as log files".
I wouldn't call this "unlikely". I've run servers out of disk space way too often in my career...
|
Opened another cockroach issue to suggest moving documented |
Fixes #4932.