doc/ceph-volume document multipath support

Signed-off-by: Alfredo Deza <adeza@redhat.com>
(cherry picked from commit 1dca5eac386ff2f67f2449700cd4bf27b81dafda)

diff --git a/doc/ceph-volume/lvm/prepare.rst b/doc/ceph-volume/lvm/prepare.rst
index 700d1216a55b65cb2f67b2d0668437359758086a..6d62b17f59f585dea55b347eaba904b01a8a0e8d 100644 (file)
--- a/doc/ceph-volume/lvm/prepare.rst
+++ b/doc/ceph-volume/lvm/prepare.rst
@@ -201,6 +201,33 @@ work for both bluestore and filestore OSDs::
     ceph-volume lvm prepare --bluestore --data vg/lv --crush-device-class foo
 
 
+.. _ceph-volume-lvm-multipath:
+
+``multipath`` support
+---------------------
+Devices that come from ``multipath`` are not supported as-is. The tool will
+refuse to consume a raw multipath device and will report a message like::
+
+    -->  RuntimeError: Cannot use device (/dev/mapper/<name>). A vg/lv path or an existing device is needed
+
+The reason for not supporting multipath is that depending on the type of the
+multipath setup, if using an active/passive array as the underlying physical
+devices, filters are required in ``lvm.conf`` to exclude the disks that are part of
+those underlying devices.
+
+It is unfeasible for ceph-volume to understand what type of configuration is
+needed for LVM to be able to work in various different multipath scenarios. The
+functionality to create the LV for you is merely a (naive) convenience,
+anything that involves different settings or configuration must be provided by
+a config management system which can then provide VGs and LVs for ceph-volume
+to consume.
+
+This situation will only arise when trying to use the ceph-volume functionality
+that creates a volume group and logical volume from a device. If a multipath
+device is already a logical volume it *should* work, given that the LVM
+configuration is done correctly to avoid issues.
+
+
 Storing metadata
 ----------------
 The following tags will get applied as part of the preparation process