rgw: updates to resharding documentation

Some minor updates to the resharding documentation with the aim of
clarifying the language and using terms consistently.

Signed-off-by: J. Eric Ivancich <ivancich@redhat.com>
(cherry picked from commit 54b6b650eeeeac0e754bd5860cd53109ba7865bd)

Conflicts:
	doc/radosgw/dynamicresharding.rst
- refrain from backporting changes to sections that aren't present in mimic

diff --git a/doc/radosgw/dynamicresharding.rst b/doc/radosgw/dynamicresharding.rst
index 2a60def8c3a90181df1249df909e1ef7c879b780..03eb1fdcc7591c365ea6b731e53a3ab64ff8341b 100644 (file)
--- a/doc/radosgw/dynamicresharding.rst
+++ b/doc/radosgw/dynamicresharding.rst
@@ -7,46 +7,49 @@ RGW Dynamic Bucket Index Resharding
 A large bucket index can lead to performance problems. In order
 to address this problem we introduced bucket index sharding.
 Until Luminous, changing the number of bucket shards (resharding)
-needed to be done offline, from Luminous we support
+needed to be done offline. Starting with Luminous we support
 online bucket resharding.
 
 Each bucket index shard can handle its entries efficiently up until
-reaching a certain threshold of entries. If this threshold is exceeded the system
-could encounter performance issues.
-The dynamic resharding feature detects this situation and increases
-automatically the number of shards used by the bucket index,
+reaching a certain threshold number of entries. If this threshold is exceeded the system
+can encounter performance issues.
+The dynamic resharding feature detects this situation and automatically
+increases the number of shards used by the bucket index,
 resulting in the reduction of the number of entries in each bucket index shard.
 This process is transparent to the user.
 
 The detection process runs:
-1. When new objects are added to the bucket
-2. In a background process that periodically scans all the buckets
-This is needed in order to deal with existng buckets in the system that are not being updated.
-A bucket that requires resharding is added to the ``reshard_log`` queue and will be
+
+1. when new objects are added to the bucket and
+2. in a background process that periodically scans all the buckets.
+
+The background process is needed in order to deal with existing buckets in the system that are not being updated.
+A bucket that requires resharding is added to the resharding queue and will be
 scheduled to be resharded later.
-The reshard threads run in the background and execute the scheduled resharding, one at a time.
+The reshard threads run in the background and execute the scheduled resharding tasks, one at a time.
 
 Multisite
 =========
-Dynamic resharding is not supported in multisite environment.
+
+Dynamic resharding is not supported in a multisite environment.
 
 
 Configuration
 =============
 
-Enable/Disable Dynamic bucket index resharding:
+Enable/Disable dynamic bucket index resharding:
 
--``rgw_dynamic_resharding``:  true/false, default: true.
+- ``rgw_dynamic_resharding``:  true/false, default: true
 
-Parameters to control the resahrding process in Ceph configuration fie:
+Configuration options that control the resharding process:
 
--``rgw_reshard_num_logs``: number of shards for the resharding log, default: 16
+- ``rgw_reshard_num_logs``: number of shards for the resharding queue, default: 16
 
--``rgw_reshard_bucket_lock_duration``: duration of lock on bucket obj during resharding, default:  120 seconds.
+- ``rgw_reshard_bucket_lock_duration``: duration, in seconds, of lock on bucket obj during resharding, default: 120 seconds
 
--``rgw_max_objs_per_shard``: maximum number of objects per bucket index shard, default: 100000 objects.
+- ``rgw_max_objs_per_shard``: maximum number of objects per bucket index shard before resharding is triggered, default: 100000 objects
 
--``rgw_reshard_thread_interval``: maximum time between rounds of reshard thread processing,  default: 600 seconds
+- ``rgw_reshard_thread_interval``: maximum time, in seconds, between rounds of resharding queue processing, default: 600 seconds
 
 
 Admin commands
@@ -66,8 +69,8 @@ List resharding queue
 
    # radosgw-admin reshard list
 
-Process/Schedule a bucket resharding
-------------------------------------
+Process tasks on the resharding queue
+-------------------------------------
 
 ::
 
@@ -83,12 +86,12 @@ Bucket resharding status
 Cancel pending bucket resharding
 --------------------------------
 
-Ongoing bucket resharding operations cannot be cancelled. ::
+Note: Ongoing bucket resharding operations cannot be cancelled. ::
 
    # radosgw-admin reshard cancel --bucket <bucket_name>
 
-Manual bucket resharding
-------------------------
+Manual immediate bucket resharding
+----------------------------------
 
 ::