Add Some Clarifications to the AutoRecovery Documentation
Descriptions of the changes in this PR:
### Motivation
I recently started using Apache Bookkeeper as part of my Apache Pulsar cluster. In learning some of the operational tasks related to managing the bookies and autorecovery, I noticed a few places where the documentation could be improved.
### Changes
The changes are all to the `AutoRecovery.md` file for version 4.12.0. They might apply to earlier versions, but I'm not sure how documentation updates are handled. My first change is to explicitly mention the way to turn off the AutoRecovery daemon on the bookie nodes. This configuration was not obvious to me as a new user of the project, and I accidentally had recovery workers running on all nodes. (Regarding that, I mention in the PR that it is possible to run the process on bookie and autorecovery nodes. Perhaps this isn't an intended use case though? If that is so, it should be mentioned in the documentation.) I also added a clarification to the `disable` auto recovery documentation because it wasn't obvious to me that running the script would stop autorecovery for the whole cluster.
Thanks!
Reviewers: Enrico Olivelli <eolivelli@gmail.com>, Sijie Guo <None>
This closes #2507 from michaeljmarshall/document-autorecovery-more
diff --git a/site/docs/4.12.0/admin/autorecovery.md b/site/docs/4.12.0/admin/autorecovery.md
index 4ff881c..5e3a8bc 100644
--- a/site/docs/4.12.0/admin/autorecovery.md
+++ b/site/docs/4.12.0/admin/autorecovery.md
@@ -45,10 +45,11 @@
* automatically detects when a {% pop bookie %} in your BookKeeper cluster has become unavailable and then
* rereplicates all the {% pop ledgers %} that were stored on that bookie.
-AutoRecovery can be run in two ways:
+AutoRecovery can be run in three ways:
1. On dedicated nodes in your BookKeeper cluster
1. On the same machines on which your bookies are running
+1. On a combination of autorecovery nodes and bookie nodes
## Running AutoRecovery
@@ -64,21 +65,24 @@
You can also start up AutoRecovery on a fresh machine if you'd like to create a dedicated cluster of AutoRecovery nodes.
+Note that if you _only_ want the AutoRecovery process to run on your dedicated AutoRecovery nodes, you must set `autoRecoveryDaemonEnabled` to `false` in the `bookkeeper` configuration. Otherwise,
+bookkeeper nodes will also handle rereplication work.
+
## Configuration
There are a handful of AutoRecovery-related configs in the [`bk_server.conf`](../../reference/config) configuration file. For a listing of those configs, see [AutoRecovery settings](../../reference/config#autorecovery-settings).
## Disable AutoRecovery
-You can disable AutoRecovery at any time, for example during maintenance. Disabling AutoRecovery ensures that bookies' data isn't unnecessarily rereplicated when the bookie is only taken down for a short period of time, for example when the bookie is being updated or the configuration if being changed.
+You can disable AutoRecovery for the whole cluster at any time, for example during maintenance. Disabling AutoRecovery ensures that bookies' data isn't unnecessarily rereplicated when the bookie is only taken down for a short period of time, for example when the bookie is being updated or the configuration if being changed.
-You can disable AutoRecover using the [`bookkeeper`](../../reference/cli#bookkeeper-shell-autorecovery) CLI tool:
+You can disable AutoRecover for the whole cluster using the [`bookkeeper`](../../reference/cli#bookkeeper-shell-autorecovery) CLI tool:
```bash
$ bin/bookkeeper shell autorecovery -disable
```
-Once disabled, you can reenable AutoRecovery using the [`enable`](../../reference/cli#bookkeeper-shell-autorecovery) shell command:
+Once disabled, you can reenable AutoRecovery for the whole cluster using the [`enable`](../../reference/cli#bookkeeper-shell-autorecovery) shell command:
```bash
$ bin/bookkeeper shell autorecovery -enable
