improve readability

Signed-off-by: Ben Ye <[email protected]>

Author: yeya24

docs/blocks-storage/store-gateway.template

@@ -54,13 +54,20 @@ The store-gateway supports two sharding strategies:
 
 - `default`
 - `shuffle-sharding`
+- `zone-stable-shuffle-sharding`
 
 The **`default`** sharding strategy spreads the blocks of each tenant across all store-gateway instances. It's the easiest form of sharding supported, but doesn't provide any workload isolation between different tenants.
 
 The **`shuffle-sharding`** strategy spreads the blocks of a tenant across a subset of store-gateway instances. This way, the number of store-gateway instances loading blocks of a single tenant is limited and the blast radius of any issue that could be introduced by the tenant's workload is limited to its shard instances.
 
 The shuffle sharding strategy can be enabled via `-store-gateway.sharding-strategy=shuffle-sharding` and requires the `-store-gateway.tenant-shard-size` flag (or their respective YAML config options) to be set to the default shard size, which is the default number of store-gateway instances each tenant should be sharded to. The shard size can then be overridden on a per-tenant basis setting the `store_gateway_tenant_shard_size` in the limits overrides.
 
+The **`zone-stable-shuffle-sharding`** strategy achieves the same as the **`shuffle-sharding`** strategy, but using a different sharding algorithm. The new sharding algorithm ensures that when zone awareness is enabled, when shard size increases or decreases by one, the replicas for any block should only change at most by one instance. This is important for querying store gateway because a block can be retried at most 3 times.
+
+Zone stable shuffle sharding can be enabled via `-store-gateway.sharding-ring.zone-stable-shuffle-sharding` CLI flag.
+
+It will become the default shuffle sharding strategy for store gateway in `v1.17.0` release and the previous shuffle sharding algorithm will be removed in `v1.18.0` release.
+
 _Please check out the [shuffle sharding documentation](../guides/shuffle-sharding.md) for more information about how it works._
 
 ### Auto-forget

docs/configuration/v1-guarantees.md

@@ -106,5 +106,5 @@ Currently experimental features are:
   - `-ingester.out-of-order-time-window` (duration) CLI flag
   - `out_of_order_time_window` (duration) field in runtime config file
 - Store Gateway Zone Stable Shuffle Sharding
-  - `-zone-stable-shuffle-sharding` CLI flag
+  - `-store-gateway.sharding-ring.zone-stable-shuffle-sharding` CLI flag
   - `zone_stable_shuffle_sharding` (boolean) field in config file

pkg/ring/ring.go

@@ -727,9 +727,6 @@ func (r *Ring) shuffleShard(identifier string, size int, lookbackPeriod time.Dur
 		if zoneStableSharding {
 			numInstancesPerZone = size / len(r.ringZones)
 			zonesWithExtraInstance = size % len(r.ringZones)
-			if zonesWithExtraInstance > 0 {
-				numInstancesPerZone++
-			}
 		} else {
 			numInstancesPerZone = shardUtil.ShuffleShardExpectedInstancesPerZone(size, len(r.ringZones))
 		}
@@ -762,7 +759,12 @@ func (r *Ring) shuffleShard(identifier string, size int, lookbackPeriod time.Dur
 		// To select one more instance while guaranteeing the "consistency" property,
 		// we do pick a random value from the generator and resolve uniqueness collisions
 		// (if any) continuing walking the ring.
-		for i := 0; i < numInstancesPerZone; i++ {
+		finalInstancesPerZone := numInstancesPerZone
+		if zonesWithExtraInstance > 0 {
+			zonesWithExtraInstance--
+			finalInstancesPerZone++
+		}
+		for i := 0; i < finalInstancesPerZone; i++ {
 			start := searchToken(tokens, random.Uint32())
 			iterations := 0
 			found := false
@@ -805,12 +807,6 @@ func (r *Ring) shuffleShard(identifier string, size int, lookbackPeriod time.Dur
 				break
 			}
 		}
-		if zoneStableSharding && zonesWithExtraInstance > 0 {
-			zonesWithExtraInstance--
-			if zonesWithExtraInstance == 0 {
-				numInstancesPerZone--
-			}
-		}
 	}
 
 	// Build a read-only ring for the shard.