Add cluster awareness and decommission docs

_api-reference/cluster-awareness.md

@@ -0,0 +1,106 @@
+---
+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 Path 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
+
+You can assign weights to zone 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. 
+
+In the following example request body, `zone_1` and `zone_2` receive 50 requests each, whereas `zone_3` is cut for from receiving requests.
+
+```
+{ 
+      "zone_1": "5", 
+      "zone_2": "5",
+      "zone_3": "0", 
+}
+```
+
+## Example: Weighted round robin search
+
+The following sample request creates a round robin shard allocation for search traffic.
+
+### Request
+
+```
+PUT /_cluster/routing/awareness/zone/weights
+{ 
+      "zone_1": "1", 
+      "zone_2": "1", 
+      "zone_3": "0"
+}
+```
+
+### Response
+
+```
+{
+     "acknowledged": true
+}
+```
+
+## Example: Get weight for a local node
+
+The following sample request gets the weight for a local node as well as any zones in your cluster. This gives you the ability to see if you local node is weighted over your zones.
+
+### Request
+
+```
+GET /_cluster/routing/awareness/zone/weights?local
+```
+
+### Response
+
+```json
+{ 
+    "zone_1": "1", 
+    "zone_2": "1", 
+    "zone_3": "0",
+    "node_weight" : "0"
+}
+```
+
+## Example: Get weights for all zones
+
+The following sample request gets weights for all zones.
+
+### Request
+
+```
+GET /_cluster/routing/awareness/<attribute>/weights
+```
+
+### Response
+
+OpenSearch responds with the weight of each zone.
+
+```json
+{
+      "zone_1": "1", 
+      "zone_2": "1", 
+      "zone_3": "0"
+}
+```
+

_api-reference/cluster-decommission.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: Cluster decommission 
+nav_order: 20
+---
+
+# Cluster decommission
+
+The cluster decommission operation adds support for zonal cluster deployments based on awareness. When a particular zone overloads with traffic, you can decommission the zone to ensure uptime during large search requests. This greatly benefits use cases with multi-zone deployment, since rolling restarts per node can take more time than decommissioning a zone. 
+
+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
+
+When recommissioning or decommissioning a zone, OpenSearch responds with the following:
+
+```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"
+}
+```
+
+
+
+

_api-reference/cluster-health.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Cluster health
-nav_order: 16
+nav_order: 17
 ---
 
 # Cluster health

_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