1 .. _rgw_dynamic_bucket_index_resharding:
3 ===================================
4 RGW Dynamic Bucket Index Resharding
5 ===================================
7 .. versionadded:: Luminous
9 A large bucket index can lead to performance problems. In order
10 to address this problem we introduced bucket index sharding.
11 Until Luminous, changing the number of bucket shards (resharding)
12 needed to be done offline. Starting with Luminous we support
13 online bucket resharding.
15 Each bucket index shard can handle its entries efficiently up until
16 reaching a certain threshold number of entries. If this threshold is
17 exceeded the system can suffer from performance issues. The dynamic
18 resharding feature detects this situation and automatically increases
19 the number of shards used by the bucket index, resulting in a
20 reduction of the number of entries in each bucket index shard. This
21 process is transparent to the user. Write I/Os to the target bucket
22 are blocked and read I/Os are not during resharding process.
24 By default dynamic bucket index resharding can only increase the
25 number of bucket index shards to 1999, although this upper-bound is a
26 configuration parameter (see Configuration below). When
27 possible, the process chooses a prime number of bucket index shards to
28 spread the number of bucket index entries across the bucket index
31 The detection process runs in a background process that periodically
32 scans all the buckets. A bucket that requires resharding is added to
33 the resharding queue and will be scheduled to be resharded later. The
34 reshard thread runs in the background and execute the scheduled
35 resharding tasks, one at a time.
40 Dynamic resharding is not supported in a multisite environment.
46 Enable/Disable dynamic bucket index resharding:
48 - ``rgw_dynamic_resharding``: true/false, default: true
50 Configuration options that control the resharding process:
52 - ``rgw_max_objs_per_shard``: maximum number of objects per bucket index shard before resharding is triggered, default: 100000 objects
54 - ``rgw_max_dynamic_shards``: maximum number of shards that dynamic bucket index resharding can increase to, default: 1999
56 - ``rgw_reshard_bucket_lock_duration``: duration, in seconds, of lock on bucket obj during resharding, default: 360 seconds (i.e., 6 minutes)
58 - ``rgw_reshard_thread_interval``: maximum time, in seconds, between rounds of resharding queue processing, default: 600 seconds (i.e., 10 minutes)
60 - ``rgw_reshard_num_logs``: number of shards for the resharding queue, default: 16
65 Add a bucket to the resharding queue
66 ------------------------------------
70 # radosgw-admin reshard add --bucket <bucket_name> --num-shards <new number of shards>
77 # radosgw-admin reshard list
79 Process tasks on the resharding queue
80 -------------------------------------
84 # radosgw-admin reshard process
86 Bucket resharding status
87 ------------------------
91 # radosgw-admin reshard status --bucket <bucket_name>
93 The output is a json array of 3 objects (reshard_status, new_bucket_instance_id, num_shards) per shard.
95 For example, the output at different Dynamic Resharding stages is shown below:
97 ``1. Before resharding occurred:``
102 "reshard_status": "not-resharding",
103 "new_bucket_instance_id": "",
108 ``2. During resharding:``
113 "reshard_status": "in-progress",
114 "new_bucket_instance_id": "1179f470-2ebf-4630-8ec3-c9922da887fd.8652.1",
118 "reshard_status": "in-progress",
119 "new_bucket_instance_id": "1179f470-2ebf-4630-8ec3-c9922da887fd.8652.1",
124 ``3, After resharding completed:``
129 "reshard_status": "not-resharding",
130 "new_bucket_instance_id": "",
134 "reshard_status": "not-resharding",
135 "new_bucket_instance_id": "",
141 Cancel pending bucket resharding
142 --------------------------------
144 Note: Ongoing bucket resharding operations cannot be cancelled. ::
146 # radosgw-admin reshard cancel --bucket <bucket_name>
148 Manual immediate bucket resharding
149 ----------------------------------
153 # radosgw-admin bucket reshard --bucket <bucket_name> --num-shards <new number of shards>
155 When choosing a number of shards, the administrator should keep a
156 number of items in mind. Ideally the administrator is aiming for no
157 more than 100000 entries per shard, now and through some future point
160 Additionally, bucket index shards that are prime numbers tend to work
161 better in evenly distributing bucket index entries across the
162 shards. For example, 7001 bucket index shards is better than 7000
163 since the former is prime. A variety of web sites have lists of prime
164 numbers; search for "list of prime numbers" withy your favorite web
165 search engine to locate some web sites.
170 Clusters prior to Luminous 12.2.11 and Mimic 13.2.5 left behind stale bucket
171 instance entries, which were not automatically cleaned up. The issue also affected
172 LifeCycle policies, which were not applied to resharded buckets anymore. Both of
173 these issues can be worked around using a couple of radosgw-admin commands.
175 Stale instance management
176 -------------------------
178 List the stale instances in a cluster that are ready to be cleaned up.
182 # radosgw-admin reshard stale-instances list
184 Clean up the stale instances in a cluster. Note: cleanup of these
185 instances should only be done on a single site cluster.
189 # radosgw-admin reshard stale-instances rm
195 For clusters that had resharded instances, it is highly likely that the old
196 lifecycle processes would have flagged and deleted lifecycle processing as the
197 bucket instance changed during a reshard. While this is fixed for newer clusters
198 (from Mimic 13.2.6 and Luminous 12.2.12), older buckets that had lifecycle policies and
199 that have undergone resharding will have to be manually fixed.
201 The command to do so is:
205 # radosgw-admin lc reshard fix --bucket {bucketname}
208 As a convenience wrapper, if the ``--bucket`` argument is dropped then this
209 command will try and fix lifecycle policies for all the buckets in the cluster.
214 Objects subject to Swift object expiration on older clusters may have
215 been dropped from the log pool and never deleted after the bucket was
216 resharded. This would happen if their expiration time was before the
217 cluster was upgraded, but if their expiration was after the upgrade
218 the objects would be correctly handled. To manage these expire-stale
219 objects, radosgw-admin provides two subcommands.
225 # radosgw-admin objects expire-stale list --bucket {bucketname}
227 Displays a list of object names and expiration times in JSON format.
233 # radosgw-admin objects expire-stale rm --bucket {bucketname}
236 Initiates deletion of such objects, displaying a list of object names, expiration times, and deletion status in JSON format.