doc/rados/configuration/common.rst: expand the running multiple clusters 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 <anthony.datri@gmail.com>
fix flag

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 6a89e73fbddc5ffab51a1004a7102e6c11af7c2d..fb832c0fb773ec340c358abf4170701b1ebe810c 100644 (file)
--- a/CONTRIBUTING.rst
+++ b/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

diff --git a/doc/rados/configuration/common.rst b/doc/rados/configuration/common.rst
index fe19f6c6f0a2b7af1f79f7c363ad0d0d30d77ae1..8a65b83ecd980cf96e37eb866f523535c2850a46 100644 (file)
--- a/doc/rados/configuration/common.rst
+++ b/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