Skip to content

Commit e5bfbb9

Browse files
opensearch-trigger-bot[bot]opensearch-trigger-bot[bot]
authored
Refactor cluster routing and awareness API docs (#10145) (#10146)
1 parent 17fc965 commit e5bfbb9

File tree

1 file changed

+84
-51
lines changed

1 file changed

+84
-51
lines changed

‎_api-reference/cluster-api/cluster-awareness.md

Lines changed: 84 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Cluster routing and awareness
4-
nav_order: 20
4+
nav_order: 50
55
parent: Cluster APIs
66
has_children: false
77
redirect_from:
@@ -13,111 +13,144 @@ redirect_from:
1313
**Introduced 1.0**
1414
{: .label .label-purple }
1515

16-
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, heterogeneous instances, and routing traffic away from zones during zonal failure.
16+
To control how search traffic is routed across zones, you can assign weights to awareness attribute values. This is useful for zonal deployments, heterogeneous clusters, or routing traffic away from unhealthy zones.
17+
18+
## Prerequisites
19+
20+
Before using this API, you must configure cluster awareness attributes and node attributes. This can be done either in the `opensearch.yml` file or through the Cluster Settings API.
21+
22+
For example, to configure `zone` and `rack` awareness attributes using `opensearch.yml`, specify them as a comma-separated list:
23+
24+
```yaml
25+
cluster.routing.allocation.awareness.attributes: zone,rack
26+
```
27+
{% include copy.html %}
28+
29+
Alternatively, you can use the Cluster Settings API to configure the awareness attributes:
30+
31+
```json
32+
PUT /_cluster/settings
33+
{
34+
"persistent" : {
35+
"cluster.routing.allocation.awareness.attributes": ["zone", "rack"]
36+
}
37+
}
38+
```
39+
{% include copy-curl.html %}
40+
41+
For more information about OpenSearch settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/).
1742

1843
## Endpoints
1944

2045
```json
2146
PUT /_cluster/routing/awareness/<attribute>/weights
2247
GET /_cluster/routing/awareness/<attribute>/weights?local
2348
GET /_cluster/routing/awareness/<attribute>/weights
49+
DELETE /_cluster/routing/awareness/<attribute>/weights
2450
```
2551

2652
## Path parameters
2753

28-
Parameter | Type | Description
54+
The following table lists the available path parameters. All path parameters are optional.
55+
56+
Parameter | Data type | Description
2957
:--- | :--- | :---
30-
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.
58+
`<attribute>` | String | The name of the configured awareness attribute (for example, `zone`). The attribute specified in the path determines which awareness attribute the weights apply to.
3159

32-
## Request body fields
60+
## Query parameters
3361

34-
Parameter | Type | Description
35-
:--- | :--- | :---
36-
weights | JSON object | Assigns weights to attributes within the request body of the PUT request. Weights can be set in any ratio, for example, 2:3:5. In a 2:3:5 ratio with 3 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 does not receive any search traffic.
37-
_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.
62+
The following table lists the available query parameters. All query parameters are optional.
3863

64+
| Parameter | Data type | Description |
65+
| :--- | :--- | :--- |
66+
| `local` | Boolean | Can be provided in a `GET` request only. If `true`, the request retrieves information from the node that receives the request instead of from the cluster manager node. Default is `false`.|
3967

40-
In the following example request body, `zone_1` and `zone_2` receive 50 requests each, whereas `zone_3` is prevented from receiving requests:
68+
## Request body fields
4169

42-
```
43-
{
44-
"weights":
45-
{
46-
"zone_1": "5",
47-
"zone_2": "5",
48-
"zone_3": "0"
49-
}
50-
"_version" : 1
51-
}
52-
```
70+
The following table lists the available request body fields for the `PUT` and `DELETE` methods.
5371

54-
## Example requests
72+
| Parameter | Data type | Applicable method | Description |
73+
| :--- | :--- | :--- | :--- |
74+
| `weights` | Object | `PUT` | Specifies custom weights for the awareness attribute values. The weights influence how search requests are distributed across zones or other awareness attribute values. Weights are relative and can use any ratio. For example, in a `2:3:5` ratio across three zones, 20%, 30%, and 50% of requests are routed to the respective zones. A weight of `0` excludes a zone from receiving search traffic. Required for the `PUT` method. |
75+
| `_version` | Integer | `PUT`, `DELETE` | Used for optimistic concurrency control (OCC). Ensures that changes are applied only if the current version matches, preventing conflicting updates. The version is incremented after each succesful `PUT` or `DELETE` operation. To initiate concurrency control, you must set `_version` to `-1` in the initial request. Required for the `PUT` and `DELETE` methods. |
5576

56-
### Weighted round robin search
5777

58-
The following example request creates a round robin shard allocation for search traffic by using an undefined ratio:
78+
## Example request: Weighted round-robin search
5979

80+
The following example request creates a round-robin shard allocation for search traffic between two zones while excluding a third zone from receiving any traffic:
6081

6182
```json
6283
PUT /_cluster/routing/awareness/zone/weights
6384
{
64-
"weights":
65-
{
66-
"zone_1": "1",
67-
"zone_2": "1",
68-
"zone_3": "0"
69-
}
70-
"_version" : 1
85+
"weights":
86+
{
87+
"zone_1": "1",
88+
"zone_2": "1",
89+
"zone_3": "0"
90+
},
91+
"_version" : -1
7192
}
7293
```
7394
{% include copy-curl.html %}
7495

96+
After this request, the `_version` increments to `0`.
97+
98+
To create a shard allocation for multiple awareness attributes, send a separate request for each attribute.
7599

76-
### Getting weights for all zones
100+
## Example request: Updating the configuration
77101

78-
The following example request gets weights for all zones.
102+
The `PUT` request fully replaces the existing weight configuration for the specified awareness attribute. Any values omitted in the request are removed from the configuration. For example, the following request updates the weights for zones 1 and 3 and removes zone 2:
79103

80104
```json
81-
GET /_cluster/routing/awareness/zone/weights
105+
PUT /_cluster/routing/awareness/zone/weights
106+
{
107+
"weights":
108+
{
109+
"zone_1": "2",
110+
"zone_3": "1"
111+
},
112+
"_version" : 0
113+
}
82114
```
83115
{% include copy-curl.html %}
84116

117+
After this request, the `_version` increments to `1`.
85118

86-
### Deleting weights
119+
## Example request: Viewing the configuration
87120

88-
You can remove your weight ratio for each zone using the `DELETE` method:
121+
To view the current weight configuration and its version, send the following request. Use the returned version number in subsequent update or delete requests:
89122

90123
```json
91-
DELETE /_cluster/routing/awareness/zone/weights
124+
GET /_cluster/routing/awareness/zone/weights
92125
```
93126
{% include copy-curl.html %}
94127

95-
## Example responses
96-
97-
OpenSearch typically responds with the following when successfully allocating shards:
128+
## Example response
98129

99130
```json
100131
{
101-
"acknowledged": true
132+
"weights": {
133+
"zone_1": "2.0",
134+
"zone_3": "1.0"
135+
},
136+
"_version": 1,
137+
"discovered_cluster_manager": true
102138
}
103139
```
104140

105-
### Getting weights for all zone
141+
## Example request: Deleting the configuration
106142

107-
OpenSearch responds with the weight of each zone:
143+
To remove a weight configuration, provide the current version in a `DELETE` request:
108144

109145
```json
146+
DELETE /_cluster/routing/awareness/zone/weights
110147
{
111-
"weights":
112-
{
113-
114-
"zone_1": "1.0",
115-
"zone_2": "1.0",
116-
"zone_3": "0.0"
117-
},
118-
"_version":1
148+
"_version": 1
119149
}
150+
```
151+
{% include copy-curl.html %}
120152

153+
After this request, the `_version` increments to `2`.
121154

122155
## Next steps
123156

0 commit comments

Comments
 (0)