doc/rados/operations: add kernel client procedure to read balancer documentation

As of now, the kernel client does not support `pg-upmap-primary`. I have
added some troubleshooting steps to help users who are unable to
mount images and filesystems with the kernel client while using `pg-upmap-primary`.

Once the feature is supported by the kernel client, users will be able
to perform mounts along with `pg-upmap-primary`.

Fixes: https://tracker.ceph.com/issues/72897
Signed-off-by: Laura Flores <lflores@ibm.com>

diff --git a/doc/rados/operations/read-balancer.rst b/doc/rados/operations/read-balancer.rst
index 7f74e81d1bde41397ca69613cdf6b757902503f1..ca5caa9ccb83af91cc67e20524437655cde50759 100644 (file)
--- a/doc/rados/operations/read-balancer.rst
+++ b/doc/rados/operations/read-balancer.rst
@@ -130,3 +130,44 @@ If you need to clear **all** ``pg-upmap-primary`` mappings in your cluster, you
 .. prompt:: bash $
 
    ceph osd rm-pg-upmap-primary-all
+
+Unable to Use Kernel Client
+---------------------------
+
+If you are unable to use the kernel client to map RBD images or mount a filesystem while
+``pg-upmap-primary`` mappings are in your cluster, this is because ``pg-upmap-primary``
+is not yet supported by the kernel client (as of 2025-09-08).
+
+Follow these steps to confirm this scenario:
+
+1. Confirm that your cluster contains ``pg-upmap-primary`` mappings:
+
+.. prompt:: bash $
+
+   ceph osd dump | grep "pg_upmap_primary"
+
+2. Check for this error message in the kernel log:
+
+.. code-block:: console
+
+   $ dmesg | tail
+   
+   [73393.901029] libceph: mon2 (1)10.64.24.186:6789 feature set mismatch, my 2f018fb87aa4aafe < server's 2f018fb8faa4aafe, missing 80000000
+   [73393.901037] libceph: mon2 (1)10.64.24.186:6789 missing required protocol features
+
+Those details confirm that the cluster is using features that the kernel client doesn't support.
+Until the kernel client supports ``pg-upmap-primary``, you must remove the mappings to successfully
+perform mounts. You may do so with the following commands:
+
+1. If using the balancer module, change the mode back to one that does not use ``pg-upmap-primary``.
+   This prevents additional mappings from being made:
+
+.. prompt:: bash $
+
+   ceph balancer mode upmap
+
+2. Remove all ``pg-upmap-primary`` mappings:
+
+.. prompt:: bash $
+
+   ceph osd rm-pg-upmap-primary-all