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-Tag: testing/wip-khiremat-testing-20250422.120708-squid-debug~71^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=06fd4bc9be650ad1873665097e4a137063307f77;p=ceph-ci.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 was modified to have the release note under the v19.2.2 section.
---

diff --git a/PendingReleaseNotes b/PendingReleaseNotes
index 05750c27605..acbf5fc7f24 100644
--- a/PendingReleaseNotes
+++ b/PendingReleaseNotes
@@ -58,6 +58,12 @@
 * RGW: PutObjectLockConfiguration can now be used to enable S3 Object Lock on an
   existing versioning-enabled bucket that was not created with Object Lock enabled.
 
+* 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.0.0
 
 * ceph: a new --daemon-output-file switch is available for `ceph tell` commands
diff --git a/doc/rados/operations/read-balancer.rst b/doc/rados/operations/read-balancer.rst
index a2c189dbb16..7f74e81d1bd 100644
--- 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