Add cluster awareness and decommission docs

_api-reference/cluster-awareness.md

@@ -0,0 +1,121 @@
+---
+layout: default
+title: Cluster routing and awareness
+nav_order: 16
+---
+
+# Cluster routing and awareness
+
+To control the distribution of search or HTTP traffic, you can use the weights per awareness attribute to control the distribution of search or HTTP traffic across zones. This is commonly used for zonal deployments, heterogenous instances, and weighing traffic away from zones during zonal failure.
+
+## HTTP and ath methods
+
+```
+PUT /_cluster/routing/awareness/<attribute>/weights
+GET /_cluster/routing/awareness/<attribute>/weights?local
+GET /_cluster/routing/awareness/<attribute>/weights
+```
+
+## Path parameters
+
+Parameter | Type | Description
+:--- | :--- | :---
+attribute | String | The name of the awareness attribute, usually `zone`. The attribute name must match the values listed in the request body when assigning weights to zones.
+
+## Request body parameters
+
+Parameter | Type | Description
+:--- | :--- | :---
+weights | JSON object | Assigns weights to attributes within the request body of the PUT request. Weights can be set in any ration, for example, 2:3:5. In a 2:3:5 ratio with three zones, for every 100 requests sent to the cluster, each zone would receive either 20, 30, or 50 search requests in a random order. When assigned a weight of `0`, the zone is cut off from an search traffic. 
+_version | String | Implements Optimistic concurrency control (OCC) through versioning. The parameter uses simple versioning, such as `1`, and increments upward based on each subsequent modification. This allows any servers from which a request originates to validate whether or not a zone has been modified. 
+
+
+In the following example request body, `zone_1` and `zone_2` receive 50 requests each, whereas `zone_3` is cut for from receiving requests:
+
+```
+{ 
+      "weights":
+      {
+        "zone_1": "5", 
+        "zone_2": "5", 
+        "zone_3": "0"
+      }
+      "_version" : 1
+}
+```
+
+## Example: Weighted round robin search
+
+The following sample request creates a round robin shard allocation for search traffic, using an undefined ratio:
+
+### Request
+
+PUT /_cluster/routing/awareness/zone/weights
+{ 
+      "weights":
+      {
+        "zone_1": "1", 
+        "zone_2": "1", 
+        "zone_3": "0"
+      }
+      "_version" : 1
+}
+
+### Response
+
+```
+{
+     "acknowledged": true
+}
+```
+
+
+## Example: Get weights for all zones
+
+The following sample request gets weights for all zones:
+
+### Request
+
+```
+GET /_cluster/routing/awareness/zone/weights
+```
+
+### Response
+
+OpenSearch responds with the weight of each zone.
+
+```json
+{
+      "weights":
+      {
+
+        "zone_1": "1.0", 
+        "zone_2": "1.0", 
+        "zone_3": "0.0"
+      },
+      "_version":1
+}
+```
+
+## Example: Delete weights
+
+You can remove your weight ratio for each zone using the `DELETE` method.
+
+### Request
+
+```
+DELETE /_cluster/routing/awareness/zone/weights
+```
+
+### Response
+
+```json
+{
+   "_version":1
+}
+```
+
+## Next steps
+
+- For more information about zone commissioning, see [Cluster decommission]({{site.url}}{{site.baseurl}}/api-reference/cluster-decommission/).
+- For more information about allocation awareness, see [Cluster formation]({{site.url}}{{site.baseurl}}/opensearch/cluster/#advanced-step-6-configure-shard-allocation-awareness-or-forced-awareness)

_api-reference/cluster-decommission.md

@@ -0,0 +1,80 @@
+---
+layout: default
+title: Cluster decommission 
+nav_order: 20
+---
+
+# Cluster decommission
+
+The cluster decommission operation adds support decommissioning based on awareness. It greatly benefits uses with multi-zone deployments, where awareness attributes, such as `zones`, can aid in applying new upgrades to a cluster in controlled fashion. This is especially useful during outages, in which case, you can decommission that unhealthy zone to prevent replication requests from getting stalled and prevent your request backlog from becoming to large.
+
+For more information on allocation awareness, see [Shard allocation awareness]({{site.url}}{{site.baseurl}}//opensearch/cluster/#shard-allocation-awareness)
+
+
+## Path and HTTP methods
+
+```
+PUT  /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value}
+GET  /_cluster/decommission/awareness/{awareness_attribute_name}/_status
+DELETE /_cluster/decommission/awareness
+```
+
+## URL parameters
+
+Parameter | Type | Description
+:--- | :--- | :---
+awareness_attribute_name | String | The name of awareness attribute, usually `zone`.
+awareness_attribute_value | String | The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method.
+
+
+## Example: Decommission and recommission a zone
+
+You can use the following sample requests to decommission and recommission a zone:
+
+### Request
+
+The following sample request decommissions `zone-a`:
+
+```
+PUT /_cluster/decommission/awareness/<zone>/<zone-a>
+```
+
+If you want to recommission a decommissioned zone, you can use the `DELETE` method.
+
+```
+DELETE /_cluster/decommission/awareness
+```
+
+### Response
+
+
+```json
+{
+      "acknowledged": true
+}
+```
+
+## Example: Get zone decommission status
+
+The following sample requests returns the decommission status of all zones.
+
+### Request
+
+```
+GET /_cluster/decommission/awareness/zone/_status
+```
+
+
+### Response
+
+```json
+{
+     "zone-1": "INIT | DRAINING | IN_PROGRESS | SUCCESSFUL | FAILED"
+}
+```
+
+
+## Next steps
+
+- For more information about zone awareness and weight, see [Cluster awareness]({{site.url}}{{site.baseurl}}/api-reference/cluster-awareness/).
+- For more information about allocation awareness, see [Cluster formation]({{site.url}}{{site.baseurl}}/opensearch/cluster/#advanced-step-6-configure-shard-allocation-awareness-or-forced-awareness).

_api-reference/cluster-health.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Cluster health
-nav_order: 16
+nav_order: 17
 ---
 
 # Cluster health
@@ -47,6 +47,7 @@ wait_for_events | Enum | Wait until all currently queued events with the given p
 wait_for_no_relocating_shards | Boolean | Whether to wait until there are no relocating shards in the cluster. Default is false.
 wait_for_no_initializing_shards | Boolean | Whether to wait until there are no initializing shards in the cluster. Default is false.
 wait_for_status | Enum | Wait until the cluster health reaches the specified status or better. Supported values are `green`, `yellow`, and `red`.
+weights | JSON object | Assigns weights to attributes within the request body of the PUT request. Weights can be set in any ration, for example, 2:3:5. In a 2:3:5 ratio with three zones, for every 100 requests sent to the cluster, each zone would receive either 20, 30, or 50 search requests in a random order. When assigned a weight of `0`, the zone is cut off from an search traffic. 
 
 #### Sample request
 

_api-reference/cluster-settings.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Cluster settings
-nav_order: 17
+nav_order: 18
 ---
 
 # Cluster settings

_api-reference/count.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Count
-nav_order: 20
+nav_order: 21
 ---
 
 # Count