https://github.com/ceph/ceph/pull/58057 represents the beginning of a response to issue II (Ceph command-presentation convention standardization) in Joel's email above. I plan to add angle brackets (or something like them) in the near future. I think it might be worth putting down here in writing that the addition of angle brackets to the documentation will be an ongoing and habitual process and not a one-time, one-shot deal. Zac On Wednesday, June 12th, 2024 at 4:35 AM, Anthony D'Atri <aad@xxxxxxxxxxxxxx> wrote: > > > Custom names were never really 100% implemented, and I would not be surprised if they don't work in Reef. > > > On Jun 11, 2024, at 14:02, Joel Davidow jdavidow@xxxxxxx wrote: > > > > Zac, > > > > Thanks for your super-fast response and action on this. Those four items > > are great and the corresponding email as reformatted looks good. > > > > Jana's point about cluster names is a good one. The deprecation of custom > > cluster names, which appears to have started in octopus per > > https://docs.ceph.com/en/octopus/rados/configuration/common/, alleviates > > that confusion going forward but does not help with clusters already > > deployed with custom names. > > > > Thanks again, > > Joel > > > > On Tue, Jun 11, 2024 at 2:26 AM Janne Johansson icepic.dz@xxxxxxxxx wrote: > > > > > > 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. > > > > > > Yes, this is one of my main gripes. Many of the doc parts should more > > > visibly point out which words or parts of names are the ones that you > > > chose (by selecting a hostname for instance), it gets weird when you > > > see "mon-1" or "client.rgw.rgw1" and you don't know which of those are > > > to be changed to suit your environment and which are not. Sometimes > > > the "ceph" word sneaks into paths because it is the name of the > > > software (duh) but sometimes because it is the clustername. Now I > > > don't hope many people change their clustername, but if you did, docs > > > would be hard to follow in order to figure out where to replace "ceph" > > > with your cluster name. > > > > > > > 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. > > > > > > -- > > > May the most significant bit of your life be positive. > > > > _______________________________________________ > > 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 _______________________________________________ ceph-users mailing list -- ceph-users@xxxxxxx To unsubscribe send an email to ceph-users-leave@xxxxxxx
 |