Joel, Thank you for this message. This is a model of what in a perfect world user communication with upstream documentation could be. I identify four things in your message that I can work on immediately: 1. leader/peon documentation improvement 2. Ceph command-presentation convention standardization 3. Standardizing the strings returned by various monitor-related commands 4. alpha notation -- not observed by Davidow in the field in cephadm clusters Here are my thoughts, respectively: 1. I've already incorporated your suggestion into the documentation: https://github.com/ceph/ceph/pull/57957. Thank you for this. 2. For two years, I have kept notes about adding braces and brackets and angle brackets to the documentation to clear up these ambiguities. I will begin here. 3. This is far beyond my art, but a man's reach must exceed his grasp, or what's a heaven for? I'll ask if anyone upstream can do anything about this. 4. I will ask Radoslaw about this. I have quoted your email in full below, and I have numbered the four parts of your email with the schema I've used here. I hope that it is formatted correctly. Zac Dover Upstream Documentation Ceph Foundation On Tuesday, June 11th, 2024 at 5:33 AM, Joel Davidow <jdavidow@xxxxxxx> wrote: > > > 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. I > 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." > II > 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. III > 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. IV > 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 _______________________________________________ ceph-users mailing list -- ceph-users@xxxxxxx To unsubscribe send an email to ceph-users-leave@xxxxxxx
 |