doc: describe metadata_heap cleanup

Fixes: http://tracker.ceph.com/issues/18174
Signed-off-by: Dan van der Ster <daniel.vanderster@cern.ch>
(cherry picked from commit e76604224c0e74bbb3350743910d263c6591fd26)

diff --git a/doc/radosgw/pools.rst b/doc/radosgw/pools.rst
index 2d88a3c103b30da4730d0b866db26bee04b078f3..a904883b36c57553cc7e81ddf250afa176e26e25 100644 (file)
--- a/doc/radosgw/pools.rst
+++ b/doc/radosgw/pools.rst
@@ -22,6 +22,8 @@ placement groups for these pools. See
 `Pools <http://docs.ceph.com/docs/master/rados/operations/pools/#pools>`__
 for details on pool creation.
 
+.. _radosgw-pool-namespaces:
+
 Pool Namespaces
 ===============
 

diff --git a/doc/radosgw/troubleshooting.rst b/doc/radosgw/troubleshooting.rst
index 69c2627258b7a0a4d31a93d443cd05f99ab3cea5..4a084e82a7ab5b3a1aa41562d361d369e520a0cd 100644 (file)
--- a/doc/radosgw/troubleshooting.rst
+++ b/doc/radosgw/troubleshooting.rst
@@ -175,3 +175,34 @@ Also, check to ensure that the default site is disabled. ::
   
   
   
+Numerous objects in default.rgw.meta pool
+=========================================
+
+Clusters created prior to *jewel* have a metadata archival feature enabled by default, using the ``default.rgw.meta`` pool.
+This archive keeps all old versions of user and bucket metadata, resulting in large numbers of objects in the ``default.rgw.meta`` pool.
+
+Disabling the Metadata Heap
+---------------------------
+
+Users who want to disable this feature going forward should set the ``metadata_heap`` field to an empty string ``""``::
+
+  $ radosgw-admin zone get --rgw-zone=default > zone.json
+  [edit zone.json, setting "metadata_heap": ""]
+  $ radosgw-admin zone set --rgw-zone=default --infile=zone.json
+  $ radosgw-admin period update --commit
+
+This will stop new metadata from being written to the ``default.rgw.meta`` pool, but does not remove any existing objects or pool.
+
+Cleaning the Metadata Heap Pool
+-------------------------------
+
+Clusters created prior to *jewel* normally use ``default.rgw.meta`` only for the metadata archival feature.
+
+However, from *luminous* onwards, radosgw uses :ref:`Pool Namespaces <radosgw-pool-namespaces>` within ``default.rgw.meta`` for an entirely different purpose, that is, to store ``user_keys`` and other critical metadata.
+
+Users should check zone configuration before proceeding any cleanup procedures::
+
+  $ radosgw-admin zone get --rgw-zone=default | grep default.rgw.meta
+  [should not match any strings]
+
+Having confirmed that the pool is not used for any purpose, users may safely delete all objects in the ``default.rgw.meta`` pool, or optionally, delete the entire pool itself.