doc/rados: improve leader/peon monitor explanation

Add an explanation of leader-peon conditions that obtain when the
cluster is in the "HEALTH_OK" state. Previously, the text discussed
these two monitor states only in the context of a health detail entry.

This improvement to the documentation was suggested on the [ceph-users]
email list by Joel Davidow. This email, an absolute model of user
engagement with an upstream project, can be reviewed here: https://lists.ceph.io/hyperkitty/list/ceph-users@ceph.io/message/KF67F5TXFSSTPXV7EKL6JKLA5KZQDLDQ/

I will list Joel Davidow here as the co-author for the sake of more
expediently getting this change into the documentation, but though he is
listed as the co-author, he is the true author.

Co-authored-by: Joel Davidow <jdavidow@nso.edu>
Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 6fb9a5ef817eda5184d51ebcb425a6091ca82299)

diff --git a/doc/rados/troubleshooting/troubleshooting-mon.rst b/doc/rados/troubleshooting/troubleshooting-mon.rst
index ab145e46e9acaee4d5ca579e275720388c84b066..4a92fd582b17197c09139d4bcebda92ff3a8111f 100644 (file)
--- a/doc/rados/troubleshooting/troubleshooting-mon.rst
+++ b/doc/rados/troubleshooting/troubleshooting-mon.rst
@@ -316,6 +316,12 @@ detail`` returns a message similar to the following::
 
 **What does it mean when a Monitor's state is ``leader`` or ``peon``?**
 
+  During normal Ceph operations when the cluster is in the ``HEALTH_OK`` state,
+  one monitor in the Ceph cluster is in the ``leader`` state and the rest of
+  the monitors are in the ``peon`` state. The state of a given monitor can be
+  determined by examining the value of the state key returned by the command
+  ``ceph tell <mon_name> mon_status``.
+
   If ``ceph health detail`` shows that the Monitor is in the ``leader`` state
   or in the ``peon`` state, it is likely that clock skew is present. Follow the
   instructions in `Clock Skews`_. If you have followed those instructions and