As this is my first submission to the Ceph docs, I want to start by saying a big thank you to the Ceph team for all the efforts that have been put into improving the docs. The improvements already made have been many and have made it easier for me to operate Ceph. In https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-mon/#the-cluster-has-quorum-but-at-least-one-monitor-is-down, the section "What does it mean when a Monitor’s state is ``leader`` or ``peon``?" discusses those two mon states only in the context of an issue that has a health detail entry. However, the title of that section is not scoped to just that particular case and so could lead to confusion because during normal Ceph operations, there is a mon that has state leader and the other mons have state peon, as can be seen by the values of state returned by ceph tell <mon_name> mon_status. To alleviate any such confusion, I recommend inserting the following before the existing text in that section: "During normal Ceph operations when the cluster is in the HEALTH_OK state, one monitor in the Ceph cluster will be in the leader state and the rest of the monitors will be in the peon state. The state of a given monitor can be determined by examining the value of the state key returned by ceph tell <mon_name> mon_status." Note the difference of convention in ceph command presentation. In https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-mon/#understanding-mon-status, mon.X uses X to represent the portion of the command to be replaced by the operator with a specific value. However, that may not be clear to all readers, some of whom may read that as a literal X. I recommend switching convention to something that makes visually explicit any portion of a command that an operator has to replace with a specific value. One such convention is to use <> as delimiters marking the portion of a command that an operator has to replace with a specific value, minus the delimiters themselves. I'm sure there are other conventions that would accomplish the same goal and provide the <> convention as an example only. Also, the actual name of a mon is not clear due to the variety of mon name formats. The value of the NAME column returned by ceph orch ps --daemon-type mon and the return from ceph mon dump follow the format of mon.<host> whereas the value of name returned by ceph tell <mon_name> mon_status, the mon line returned by ceph -s, and the return from ceph mon stat follow the format of <host>. Unifying the return for the mon name value of all those commands could be helpful in establishing the format of a mon name, though that is probably easier said than done. In addition, in https://docs.ceph.com/en/latest/rados/configuration/mon-config-ref/#configuring-monitors, mon names are stated to use alpha notation by convention, but that convention is not followed by cephadm in the clusters that I've deployed. Cephadm also uses a minimal ceph.conf file with configs in the mon database. I recommend this section be updated to mention those changes. If there is a way to explain what a mon name is or how it is formatted, perhaps adding that to that same section would be good. Thanks again for the on-going work to improve the Ceph docs! Joel _______________________________________________ ceph-users mailing list -- ceph-users@xxxxxxx To unsubscribe send an email to ceph-users-leave@xxxxxxx
 |