PendingReleaseNotes; doc/rados/operations: document "rm-pg-upmap-primary-{all}" commands

Added a release note for `ceph osd rm-pg-upmap-primary` and documentation to
complement #62190.

Signed-off-by: Laura Flores <lflores@ibm.com>

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index 904f07e774df3ebbf70e8b0ab969f7919c56e798..31997d930c27d4f2191ce8f4b4b97f73007931d1 100644 (file)
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -107,6 +107,11 @@
   metadata and data pool names to be used for creating the volume. If either
   is not passed or if either is a non-empty pool, the command will abort.
 
+* RADOS: A new command, `ceph osd rm-pg-upmap-primary-all`, has been added that allows
+  users to clear all pg-upmap-primary mappings in the osdmap when desired.
+  Related trackers:
+   - https://tracker.ceph.com/issues/67179
+   - https://tracker.ceph.com/issues/66867
 
 >=19.2.1
 

diff --git a/doc/rados/operations/read-balancer.rst b/doc/rados/operations/read-balancer.rst
index a2c189dbb16fab0b8651b6e34a30137ec14d5947..7f74e81d1bde41397ca69613cdf6b757902503f1 100644 (file)
--- a/doc/rados/operations/read-balancer.rst
+++ b/doc/rados/operations/read-balancer.rst
@@ -103,3 +103,30 @@ Primaries are updated with an offline optimizer that is built into the
 To see some details about what the tool is doing, you can pass
 ``--debug-osd 10`` to ``osdmaptool``. To see even more details, pass
 ``--debug-osd 20`` to ``osdmaptool``.
+
+Troubleshooting
+===============
+
+Removing pg-upmap-primary mappings
+------------------------------------
+
+For scenarios where you need to manually remove ``pg-upmap-primary`` mappings, Ceph provides the following
+developer-level commands. These commands should be used with caution, as they directly modify
+primary PG mappings and can impact read performance (this excludes any data movement).
+
+.. note::
+
+  Users affected by `#66867 <https://tracker.ceph.com/issues/66867>`_ or `#61948 <https://tracker.ceph.com/issues/61948>`_
+  may find these commands useful when dealing with unexpected ``pg-upmap-primary`` behavior.
+
+To remove a specific ``pg-upmap-primary`` mapping, use:
+
+.. prompt:: bash $
+
+   ceph osd rm-pg-upmap-primary <pgid>
+
+If you need to clear **all** ``pg-upmap-primary`` mappings in your cluster, you may use:
+
+.. prompt:: bash $
+
+   ceph osd rm-pg-upmap-primary-all