doc/rados/configuration/common.rst: expand the running multiple clust…

…ers section

Add context to the existing note that running custom names, and thus
multiple clusters on the same hardware, are both deprecated and should
not be done.  This should fulfill tracker #24143.

Fixes: https://tracker.ceph.com/issues/24143
Signed-off-by: Anthony D'Atri <[email protected]>

fix flag

CONTRIBUTING.rst

@@ -1,4 +1,4 @@
-For the general process of submitting patches to ceph, read the below
+For the general process of submitting patches to Ceph, read the below
 
 `Submitting Patches`_
 
@@ -9,10 +9,10 @@ For documentation patches the following guide will help you get started
 Performance enhancements must come with test data and detailed
 explanations.
 
-Code cleanup is appreciated along with a patch that fixes a bug or
-implements a feature. Except on rare occasions, code cleanup that only
-involve coding style or whitespace modifications are discouraged,
-primarily because they cause problems when rebasing and backporting.
+Code cleanup is appreciated, as are patches that fix bugs or
+implement features. Except on rare occasions, code cleanup that only
+relates to coding style or modifies whitespace is discouraged,
+primarily because it can cause problems when rebasing and backporting.
 
 .. _Submitting Patches: SubmittingPatches.rst
 .. _Documenting Ceph:  doc/start/documenting-ceph.rst

doc/rados/configuration/common.rst

@@ -186,15 +186,32 @@ Example ceph.conf
 Running Multiple Clusters (DEPRECATED)
 ======================================
 
-Some Ceph CLI commands take a ``-c`` (cluster name) option. This option is
-present purely for backward compatibility. You should not attempt to deploy
-or run multiple clusters on the same hardware, and it is recommended to always
-leave the cluster name as the default ("ceph").
-
-If you need to allow multiple clusters to exist on the same host, please use
+Each Ceph cluster has an internal name that is used as part of configuration
+and log file names as well as directory and mountpoint names.  This name
+defaults to "ceph".  Previous releases of Ceph allowed one to specify a custom
+name instead, for example "ceph2".  This was intended to faciliate running
+multiple logical clusters on the same physical hardware, but in practice this
+was rarely exploited and should no longer be attempted.  Prior documentation
+could also be misinterpreted as requiring unique cluster names in order to
+use ``rbd-mirror``.
+
+Custom cluster names are now considered deprecated and the ability to deploy
+them has already been removed from some tools, though existing custom name
+deployments continue to operate.  The ability to run and manage clusters with
+custom names may be progressively removed by future Ceph releases, so it is
+strongly recommended to deploy all new clusters with the default name "ceph".
+
+Some Ceph CLI commands accept an optional ``--cluster`` (cluster name) option. This
+option is present purely for backward compatibility and need not be accomodated
+by new tools and deployments.
+
+If you do need to allow multiple clusters to exist on the same host, please use
 :ref:`cephadm`, which uses containers to fully isolate each cluster.
 
 
+
+
+
 .. _Hardware Recommendations: ../../../start/hardware-recommendations
 .. _Network Configuration Reference: ../network-config-ref
 .. _OSD Config Reference: ../osd-config-ref