doc: warn against default cephadm shell for ceph-volume

This commit documents that ceph-volume should not be run in a plain
cephadm shell session because default bind mounts are insufficient.
It describes the enriched -m example, how to retrieve the bootstrap-osd
keyring, and mentions that manual ceph-volume use outside ceph orch is
mainly for debug or dev.

Signed-off-by: Guillaume Abrioux <gabrioux@ibm.com>

diff --git a/doc/ceph-volume/intro.rst b/doc/ceph-volume/intro.rst
index 8416e0c9d8d0430e1475e498c26c998df5359b58..2e15348856cd7bb9dcc572d4cd22bd8c71d06aab 100644 (file)
--- a/doc/ceph-volume/intro.rst
+++ b/doc/ceph-volume/intro.rst
@@ -11,6 +11,41 @@ that come installed for Ceph. These rules allow automatic detection of
 previously set up devices that are in turn fed into ``ceph-disk`` to activate
 them.
 
+Cephadm shell
+-------------
+Do not run ``ceph-volume`` from a container session that was started with
+``cephadm shell`` while relying on that shell's default bind mounts. By design,
+``cephadm shell`` omits several host bind mounts that ``ceph-volume`` expects
+(for example /run/udev, /run/lvm, etc.). Invoking ``ceph-volume`` in that
+environment is likely to fail or behave incorrectly.
+
+Running ``ceph-volume`` yourself, outside of what ``ceph orch`` / cephadm
+drives, is not the normal operational path: it is mainly for debugging,
+testing, or development.
+
+.. note:: Advanced use only
+
+   If you truly understand the implications, you can extend the default container
+   environment by passing ``cephadm shell`` a single ``-m`` (or ``--mount``)
+   option followed by every bind mount you need, for example:
+
+   .. code-block:: bash
+
+      cephadm shell -m /dev:/dev /run/udev:/run/udev /sys:/sys /run/lvm:/run/lvm /run/lock/lvm:/run/lock/lvm /:/rootfs
+
+   From **inside** that shell, if you still need the ``client.bootstrap-osd``
+   keyring (``cephadm shell`` does not expose it by default), you can obtain it
+   with the cluster tools available in the container, for example:
+
+   .. code-block:: bash
+
+      ceph auth get client.bootstrap-osd -o /var/lib/ceph/bootstrap-osd/ceph.keyring
+
+   Prefer doing this inside the enriched shell rather than generating key
+   material on the host and bind-mounting it in: the latter is easy to get
+   wrong, can leave sensitive files behind on the host, and is generally more
+   intrusive than running the same command from within the shell session.
+
 .. _ceph-disk-replaced:
 
 Replacing ``ceph-disk``