From: Melissa Li <melissali@redhat.com>
Date: Thu, 23 Dec 2021 22:16:07 +0000 (-0500)
Subject: doc/cephadm: warn about default enabling `osd_memory_target_autotune`
X-Git-Tag: v16.2.8~187^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=cf43a09f866c59882a51595069a45b63d3dee0e5;p=ceph.git

doc/cephadm: warn about default enabling `osd_memory_target_autotune`

Fixes: https://tracker.ceph.com/issues/51562
Signed-off-by: Melissa Li <melissali@redhat.com>
(cherry picked from commit 0fad0fde9cfddf92113817fd8311a24888523efb)

Conflicts:
	doc/cephadm/install.rst
---

diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst
index 6b0b9fd8c472..1995b8eb6ae4 100644
--- a/doc/cephadm/install.rst
+++ b/doc/cephadm/install.rst
@@ -361,7 +361,31 @@ available and unused device:
 
     ceph orch apply osd --all-available-devices
 
-Or See :ref:`cephadm-deploy-osds` for more detailed instructions.
+See :ref:`cephadm-deploy-osds` for more detailed instructions.
+
+Enabling OSD memory autotuning
+------------------------------
+
+.. warning:: By default, cephadm enables ``osd_memory_target_autotune`` on bootstrap, with ``mgr/cephadm/autotune_memory_target_ratio`` set to ``.7`` of total host memory.
+
+See :ref:`osd_autotune`.
+
+To deploy hyperconverged Ceph with TripleO, please refer to the TripleO documentation: `Scenario: Deploy Hyperconverged Ceph <https://docs.openstack.org/project-deploy-guide/tripleo-docs/latest/features/cephadm.html#scenario-deploy-hyperconverged-ceph>`_
+
+In other cases where the cluster hardware is not exclusively used by Ceph (hyperconverged),
+reduce the memory consumption of Ceph like so:
+
+  .. prompt:: bash #
+
+    # hyperconverged only:
+    ceph config set mgr mgr/cephadm/autotune_memory_target_ratio 0.2
+
+Then enable memory autotuning:
+
+  .. prompt:: bash #
+
+    ceph config set osd osd_memory_target_autotune true
+
 
 Using Ceph
 ==========
diff --git a/doc/cephadm/services/osd.rst b/doc/cephadm/services/osd.rst
index b2193cefa955..0bdea2456ab4 100644
--- a/doc/cephadm/services/osd.rst
+++ b/doc/cephadm/services/osd.rst
@@ -380,9 +380,7 @@ memory with other services, cephadm can automatically adjust the per-OSD
 memory consumption based on the total amount of RAM and the number of deployed
 OSDs.
 
-This option is enabled globally with::
-
-  ceph config set osd osd_memory_target_autotune true
+.. warning:: Cephadm sets ``osd_memory_target_autotune`` to ``true`` by default which is unsuitable for hyperconverged infrastructures.
 
 Cephadm will start with a fraction
 (``mgr/cephadm/autotune_memory_target_ratio``, which defaults to