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@nso.edu> 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/#t..., 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/#u..., 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/#configur..., 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@ceph.io To unsubscribe send an email to ceph-users-leave@ceph.io