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 05750c27605073f63e6f87dac27d4b177f979cb1..acbf5fc7f24855f439fcb8594da6eb92e4976d9c 100644 (file)
--- 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 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