From: Guillaume Abrioux Date: Tue, 5 May 2026 08:31:42 +0000 (+0200) Subject: doc: warn against default cephadm shell for ceph-volume X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F68748%2Fhead;p=ceph.git 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 --- diff --git a/doc/ceph-volume/intro.rst b/doc/ceph-volume/intro.rst index 8416e0c9d8d0..2e15348856cd 100644 --- 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``