Attention: Documentation - mon states and names
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/#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." 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. 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/#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
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
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.
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/#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.
-- May the most significant bit of your life be positive.
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@gmail.com> wrote:
Note the difference of convention in ceph command presentation. In
mon.X uses X to represent the portion of the command to be replaced by
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
an operator has to replace with a specific value, minus the delimiters themselves. I'm sure there are other conventions that would accomplish
https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-mon/#u... , the that 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/#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.
-- May the most significant bit of your life be positive.
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@nso.edu> 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@gmail.com> wrote:
Note the difference of convention in ceph command presentation. In
mon.X uses X to represent the portion of the command to be replaced by
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
an operator has to replace with a specific value, minus the delimiters themselves. I'm sure there are other conventions that would accomplish
https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-mon/#u... , the that 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/#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.
-- May the most significant bit of your life be positive.
_______________________________________________ ceph-users mailing list -- ceph-users@ceph.io To unsubscribe send an email to ceph-users-leave@ceph.io
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@dreamsnake.net> 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@nso.edu 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@gmail.com wrote:
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.
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/#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.
-- May the most significant bit of your life be positive.
_______________________________________________ ceph-users mailing list -- ceph-users@ceph.io To unsubscribe send an email to ceph-users-leave@ceph.io
_______________________________________________ ceph-users mailing list -- ceph-users@ceph.io To unsubscribe send an email to ceph-users-leave@ceph.io
participants (4)
-
Anthony D'Atri
-
Janne Johansson
-
Joel Davidow
-
Zac Dover