Improved shard allocation awareness attributes documentation (#8268)

* Added more details regarding shard allocation awareness attributes Signed-off-by: Smit Patel <[email protected]> * Update index.md Signed-off-by: Naarcha-AWS <[email protected]> * Addressed linter recommendations Signed-off-by: Smit Patel <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Smit Patel <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Update _tuning-your-cluster/index.md Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> --------- Signed-off-by: Smit Patel <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> Signed-off-by: Smit Patel <[email protected]> Co-authored-by: Smit Patel <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]> Co-authored-by: Nathan Bower <[email protected]> (cherry picked from commit ac40282) Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
opensearch-project · Sep 18, 2024 · b2eca9c · b2eca9c
1 parent 83f3e5f
commit b2eca9c
Showing 1 changed file with 18 additions and 2 deletions.
diff --git a/_tuning-your-cluster/index.md b/_tuning-your-cluster/index.md
@@ -192,11 +192,25 @@ To better understand and monitor your cluster, use the [CAT API]({{site.url}}{{s
 
 ## (Advanced) Step 6: Configure shard allocation awareness or forced awareness
 
+To further fine-tune your shard allocation, you can set custom node attributes for shard allocation awareness or forced awareness.
+
 ### Shard allocation awareness
 
-If your nodes are spread across several geographical zones, you can configure shard allocation awareness to allocate all replica shards to a zone that’s different from their primary shard.
+You can set custom node attributes on OpenSearch nodes to be used for shard allocation awareness. For example, you can set the `zone` attribute on each node to represent the zone in which the node is located. You can also use the `zone` attribute to ensure that the primary shard and its replica shards are allocated in a balanced manner across available, distinct zones. For example, maximum shard copies per zone would equal `ceil (number_of_shard_copies/number_of_distinct_zones)`.
+
+Shard allocation awareness attempts to separate primary and replica shards across multiple zones because 2 shard copies cannot be placed on the same node. When only 1 zone is available, such as after a zone failure, OpenSearch allocates replica shards to the only remaining zone. For example, if your index has a total of 5 shard copies (1 primary and 4 replicas) and nodes in 3 distinct zones, then OpenSearch will perform the following to allocate all 5 shard copies: 
+
+- Allocate fewer than 2 shards per zone, which will require at least 2 nodes in 2 zones.
+- Allocate the last shard in the third zone, with at least 1 node needed in the third zone.
+
+Alternatively, if you have 3 nodes in the first zone and 1 node in each remaining zone, then OpenSearch will allocate:
 
-With shard allocation awareness, if the nodes in one of your zones fail, you can be assured that your replica shards are spread across your other zones. It adds a layer of fault tolerance to ensure your data survives a zone failure beyond just individual node failures.
+- 2 shard copies in the first zone.
+- 1 shard copy in the remaining 2 zones.
+
+The final shard copy will remain unallocated due to the lack of nodes. 
+
+With shard allocation awareness, if the nodes in one of your zones fail, you can be assured that your replica shards are spread across your other zones, adding a layer of fault tolerance to ensure that your data survives zone failures.
 
 To configure shard allocation awareness, add zone attributes to `opensearch-d1` and `opensearch-d2`, respectively:
 
@@ -219,6 +233,8 @@ PUT _cluster/settings
 }
 ```
 
+You can also use multiple attributes for shard allocation awareness by providing the attributes as a comma-separated string, for example, `zone,rack`.
+
 You can either use `persistent` or `transient` settings. We recommend the `persistent` setting because it persists through a cluster reboot. Transient settings don't persist through a cluster reboot.
 
 Shard allocation awareness attempts to separate primary and replica shards across multiple zones. However, if only one zone is available (such as after a zone failure), OpenSearch allocates replica shards to the only remaining zone.