Cluster routing and awareness
Introduced 1.0
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.
Prerequisites
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.
For example, to configure zone and rack awareness attributes using opensearch.yml, specify them as a comma-separated list:
cluster.routing.allocation.awareness.attributes: zone,rack
Alternatively, you can use the Cluster Settings API to configure the awareness attributes:
PUT /_cluster/settings
{
"persistent" : {
"cluster.routing.allocation.awareness.attributes": ["zone", "rack"]
}
}
For more information about OpenSearch settings, see Configuring OpenSearch.
Endpoints
PUT /_cluster/routing/awareness/<attribute>/weights
GET /_cluster/routing/awareness/<attribute>/weights?local
GET /_cluster/routing/awareness/<attribute>/weights
DELETE /_cluster/routing/awareness/<attribute>/weights
Path parameters
The following table lists the available path parameters. All path parameters are optional.
| Parameter | Data type | Description |
|---|---|---|
<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. |
Query parameters
The following table lists the available query parameters. All query parameters are optional.
| Parameter | Data type | Description |
|---|---|---|
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. |
Request body fields
The following table lists the available request body fields for the PUT and DELETE methods.
| Parameter | Data type | Applicable method | Description |
|---|---|---|---|
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. |
_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. |
Example request: Weighted round-robin search
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:
PUT /_cluster/routing/awareness/zone/weights
{
"weights":
{
"zone_1": "1",
"zone_2": "1",
"zone_3": "0"
},
"_version" : -1
}
After this request, the _version increments to 0.
To create a shard allocation for multiple awareness attributes, send a separate request for each attribute.
Example request: Updating the configuration
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:
PUT /_cluster/routing/awareness/zone/weights
{
"weights":
{
"zone_1": "2",
"zone_3": "1"
},
"_version" : 0
}
After this request, the _version increments to 1.
Example request: Viewing the configuration
To view the current weight configuration and its version, send the following request. Use the returned version number in subsequent update or delete requests:
GET /_cluster/routing/awareness/zone/weights
Example response
{
"weights": {
"zone_1": "2.0",
"zone_3": "1.0"
},
"_version": 1,
"discovered_cluster_manager": true
}
Example request: Deleting the configuration
To remove a weight configuration, provide the current version in a DELETE request:
DELETE /_cluster/routing/awareness/zone/weights
{
"_version": 1
}
After this request, the _version increments to 2.
Next steps
- For more information about zone commissioning, see Cluster decommission.
- For more information about allocation awareness, see Cluster formation.