From e1d8d9b322873b2a21ed181937ba448f794110a6 Mon Sep 17 00:00:00 2001 From: Laura Flores Date: Fri, 5 Sep 2025 16:46:20 -0500 Subject: [PATCH] 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 (cherry picked from commit 546d523147873c8fc6cf4208b4fa71eb2703e9c3) --- doc/rados/operations/read-balancer.rst | 41 ++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/doc/rados/operations/read-balancer.rst b/doc/rados/operations/read-balancer.rst index 7f74e81d1bde4..ca5caa9ccb83a 100644 --- 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 -- 2.39.5