Merge pull request ceph#65419 from ljflores/wip-tracker-72897

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

Reviewed-by: Anthony D'Atri <[email protected]>
Reviewed-by: Ilya Dryomov <[email protected]>

Author: idryomov

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