From: Laura Flores <lflores@ibm.com>
Date: Thu, 20 Mar 2025 21:19:30 +0000 (-0500)
Subject: PendingReleaseNotes; doc/rados/operations: document "rm-pg-upmap-primary-{all}" commands
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F62468%2Fhead;p=ceph.git

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>
(cherry picked from commit 4dee7917bf010dc6d8e24f0ef437bd8a41c355c9)

*Note: PendingReleaseNotes changed to put the release note under v18.2.5.
---

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index 82755aceeed5..e6b0f88b4c32 100644
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -5,6 +5,12 @@
   and is now deprecated. If the NBD netlink interface is not supported by the
   kernel, then the mapping is retried using the legacy ioctl interface.
 
+* 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
+
 >=18.2.4
 --------
 
diff --git a/doc/rados/operations/read-balancer.rst b/doc/rados/operations/read-balancer.rst
index 0833e4326c9b..c9f97b6535a6 100644
--- a/doc/rados/operations/read-balancer.rst
+++ b/doc/rados/operations/read-balancer.rst
@@ -62,3 +62,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