redis: Add zone-aware routing support for Redis Cluster proxy by bellatoris · Pull Request #43012 · envoyproxy/envoy

bellatoris · 2026-01-15T07:26:36Z

Summary

Zone-aware routing reduces cross-zone network traffic and latency by preferring replicas in the same availability zone as the client. This is particularly valuable in cloud environments where cross-zone data transfer incurs additional costs.

New Configuration

redis_cluster.proto:

  // Enable zone discovery via INFO command
  google.protobuf.BoolValue enable_zone_discovery = 7;

redis_proxy.proto - New ReadPolicy values:

  - AZ_AFFINITY: Prefer same-zone replicas → any replica → primary
  - AZ_AFFINITY_REPLICAS_AND_PRIMARY: Prefer same-zone replicas → same-zone primary → any replica → primary

How It Works

  ┌─────────────────────────────────────────────────────────┐
  │              CLUSTER SLOTS Response                     │
  └─────────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │     Zone Discovery (if enable_zone_discovery=true)      │
  │     Send INFO to each node → parse availability_zone    │
  └─────────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │     Create hosts with zone in locality.zone()           │
  │     RedisShard groups replicas by zone                  │
  └─────────────────────────────────────────────────────────┘
                           │
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │     Request Routing                                     │
  │     Client zone from node.locality.zone (bootstrap)     │
  │     AZ_AFFINITY: local replicas → any replica → primary │
  └─────────────────────────────────────────────────────────┘

Limitations

Valkey only: Zone discovery relies on availability_zone field in INFO response, which is exposed by Valkey but not standard Redis.
Client zone must be configured via node.locality.zone in Envoy bootstrap config.

Risk Level: Low

This is an opt-in feature that requires explicit configuration (enable_zone_discovery: true and read_policy: AZ_AFFINITY). Existing deployments are unaffected.

Testing

Added comprehensive unit tests for zone-aware load balancing

Related Issues

Closes #43011

repokitteh-read-only · 2026-01-15T07:26:42Z

Hi @bellatoris, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #43012 was opened by bellatoris.

see: more, trace.

repokitteh-read-only · 2026-01-15T07:26:48Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #43012 was opened by bellatoris.

see: more, trace.

This change implements zone-aware routing for Redis Cluster, allowing read requests to be routed to replicas in the same availability zone as the client. Key changes: - Add enable_zone_discovery config option to redis_cluster.proto - Add az_affinity and az_affinity_replicas_and_primary read policies - Implement INFO command-based zone discovery during cluster slot updates - Store zone info in host locality for standard Envoy locality handling - RedisShard groups replicas by zone for efficient zone-aware routing Zone Discovery Flow: 1. CLUSTER SLOTS response triggers zone discovery when enabled 2. INFO command sent to each unique node to get availability_zone 3. Zones stored in host->locality().zone() when hosts are created 4. RedisShard reads zone from host locality, groups replicas by zone Read Policies: - AzAffinity: local replicas -> any replica -> primary - AzAffinityReplicasAndPrimary: local replicas -> local primary -> any replica -> primary Note: This feature currently works with Valkey only. Valkey exposes availability_zone in its INFO response. Standard Redis does not support this field. Signed-off-by: Doogie Min <doogie.min@sendbird.com>

nezdolik

Here is partial review, will need to do few more rounds

nezdolik · 2026-01-21T11:18:51Z

source/extensions/clusters/redis/redis_cluster.cc

+RedisCluster::RedisHost::create(Upstream::ClusterInfoConstSharedPtr cluster,
+                                const std::string& hostname,
+                                Network::Address::InstanceConstSharedPtr address,
+                                RedisCluster& parent, bool primary, const std::string& zone) {


please reuse existing create method and add zone as absl::optional<string>

nezdolik · 2026-01-21T11:20:31Z

source/extensions/clusters/redis/redis_cluster.cc

+std::shared_ptr<const envoy::config::core::v3::Locality>
+RedisCluster::RedisHost::makeLocalityWithZone(
+    const envoy::config::core::v3::Locality& base_locality, const std::string& zone) {
+  auto locality = std::make_shared<envoy::config::core::v3::Locality>(base_locality);


should locality be created if zone is empty? if not then you can return absl::StatusOr<std::shared_ptr<const envoy::config::core::v3::Locality>>

nezdolik · 2026-01-26T10:10:52Z

source/extensions/clusters/redis/redis_cluster.cc

+
+  // Collect unique node addresses
+  absl::flat_hash_set<std::string> unique_addresses;
+  absl::flat_hash_map<std::string, bool> address_is_primary; // track if address is primary


would not it be sufficient just to have this map and drop unique_addresses set? since address_is_primary map will also only contain unique addresses (as keys)

nezdolik · 2026-01-26T10:16:22Z

source/extensions/clusters/redis/redis_cluster.cc

+              static_cast<int>(value->type()));
+  }
+
+  uint32_t remaining = pending_zone_requests_.fetch_sub(1) - 1;


why do we need to both atomically decrement pending_zone_requests_ and do - 1 ?

nezdolik · 2026-01-26T10:17:16Z

source/extensions/clusters/redis/redis_cluster.cc

+// availability_zone:us-east-1a
+// ...
+// Note: Standard Redis does not expose availability_zone.
+std::string


nit: add const

nezdolik · 2026-01-26T10:24:18Z

And looks like tests need to be added/improved, as coverage check is failing:

FAILED: Directories not meeting coverage thresholds:
  ✗ source/extensions/clusters/redis: 84.7% (threshold: 96.6%)
  ✗ source/extensions/filters/network/common/redis: 96.4% (threshold: 96.6%)

api/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto

Rename the read policy enum values for clarity: - AZ_AFFINITY -> LOCAL_ZONE_AFFINITY - AZ_AFFINITY_REPLICAS_AND_PRIMARY -> LOCAL_ZONE_AFFINITY_REPLICAS_AND_PRIMARY Also includes minor code cleanup: - Remove redundant unique_addresses set (use address_is_primary map keys instead) - Use try_emplace instead of find+insert pattern - Use structured bindings for map iteration - Add clarifying comments for fetch_sub return value semantics - Use static constexpr for string literal constant Signed-off-by: Doogie Min <doogie.min@sendbird.com>

markdroth · 2026-01-28T17:15:22Z

/lgtm api

Add tests to improve code coverage for the Redis cluster zone discovery feature and new read policies: - Add parseAvailabilityZone tests for various INFO response formats - Add ZoneDiscoveryConfig test fixture for zone discovery testing - Add tests for LOCAL_ZONE_AFFINITY and LOCAL_ZONE_AFFINITY_REPLICAS_AND_PRIMARY read policies in client_impl_test - Add friend declaration to RedisDiscoverySession for test access These tests cover previously untested code paths in redis_cluster.cc and client_impl.cc to help meet coverage thresholds. Signed-off-by: Doogie Min <doogie.min@sendbird.com>

nezdolik · 2026-03-16T10:51:40Z

/wait

…alidation Add tests to improve coverage for source/extensions/clusters/redis/ from 96.1% to ~97.2% (threshold: 96.6%): - LoadBalancerStubMethods: exercises peekAnotherHost, selectExistingConnection, and lifetimeCallbacks stub methods on RedisClusterLoadBalancer (+9 lines) - RedisErrorResponsePortOverflow: validates that CLUSTER SLOTS responses with port > 0xffff are rejected by validateCluster (+2 lines) Signed-off-by: Doogie Min <doogie.min@sendbird.com>

…ware-routing

bellatoris · 2026-03-17T03:29:29Z

@nezdolik done

…ware-routing # Conflicts: # changelogs/current.yaml

nezdolik

overall lgtm, few nits while we wait for api review

nezdolik · 2026-03-20T12:24:11Z

source/extensions/clusters/redis/redis_cluster.cc

  absl::Status creation_status = absl::OkStatus();
-  auto ret = std::unique_ptr<RedisCluster::RedisHost>(
-      new RedisCluster::RedisHost(cluster, hostname, address, parent, primary, creation_status));
+  auto ret = std::unique_ptr<RedisCluster::RedisHost>(new RedisCluster::RedisHost(


while we are waiting for api review, could we switch std::unique_ptr<RedisCluster::RedisHost>(new RedisCluster::RedisHost( to std::make_unique<RedisCluster::RedisHost>?

nezdolik · 2026-03-20T12:28:43Z

source/extensions/clusters/redis/redis_cluster_lb.h

+    const std::string& primaryZone() const { return primary_zone_; }
+
+    // Get replicas in a specific zone. Returns nullptr if no replicas in that zone.
+    const Upstream::HostSetImpl* replicasInZone(const std::string& zone) const {


nit: return unique_ptr here instead of raw pointer

…view-fixes

- Switch to std::make_unique in RedisHost::create() by making constructor public - Return const unique_ptr& instead of raw pointer from replicasInZone() Signed-off-by: Doogie Min <doogie.min@sendbird.com>

bellatoris · 2026-03-20T17:41:13Z

overall lgtm, few nits while we wait for api review

Done, could you review again @nezdolik @markdroth ?

nezdolik · 2026-03-23T12:49:37Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces zone-aware routing for the Redis Cluster proxy, a valuable feature for reducing cross-zone traffic. The changes are well-structured, touching the API, core discovery and load balancing logic, and connection pooling. The implementation includes a new zone discovery mechanism using the INFO command, which is cleanly integrated into the existing cluster discovery session. The load balancing logic is extended to support two new read policies with clear fallback semantics. The addition of comprehensive unit and integration tests covering both the discovery and load balancing aspects is commendable. I found one high-severity memory safety issue that should be addressed.

gemini-code-assist · 2026-03-23T12:55:22Z

source/extensions/clusters/redis/redis_cluster.h

+    void onZoneResponse(const std::string& address, bool is_primary,
+                        NetworkFilters::Common::Redis::RespValuePtr&& value);
+    void onZoneDiscoveryFailure(const std::string& address, bool is_primary);


There is a potential use-after-free bug in the implementation of onZoneResponse and onZoneDiscoveryFailure. These methods are called with a const std::string& that refers to a member of a ZoneDiscoveryCallback object. Inside these methods, zone_callbacks_.erase(address) is called, which destroys the callback object and invalidates the address reference. Using this dangling reference as the key for the erase operation is undefined behavior.

A comment in onZoneResponse indicates awareness of this lifetime issue, but the implementation is still susceptible to this bug.

To fix this, you should pass the address by value to ensure the string's lifetime is extended until the function returns. The call sites in ZoneDiscoveryCallback will then create a copy, which is the desired behavior.

Suggested change

void onZoneResponse(const std::string& address, bool is_primary,

NetworkFilters::Common::Redis::RespValuePtr&& value);

void onZoneDiscoveryFailure(const std::string& address, bool is_primary);

void onZoneResponse(std::string address, bool is_primary,

NetworkFilters::Common::Redis::RespValuePtr&&& value);

void onZoneDiscoveryFailure(std::string address, bool is_primary);

nezdolik · 2026-03-23T14:16:04Z

@markdroth ptal.

…ing hazard onZoneResponse and onZoneDiscoveryFailure receive address as const ref aliasing ZoneDiscoveryCallback::address_. When zone_callbacks_.erase(address) destroys the callback, the reference becomes dangling during the erase call. Pass by value to ensure the string outlives the erase. Signed-off-by: Doogie Min <doogie.min@sendbird.com>

Signed-off-by: Doogie Min <doogie.min@sendbird.com>

bellatoris · 2026-03-24T04:17:48Z

/retest

nezdolik · 2026-03-24T10:28:00Z

@wbpcode could you do an api shepherd review?

bellatoris requested review from mattklein123 and nezdolik as code owners January 15, 2026 07:26

repokitteh-read-only bot added the api label Jan 15, 2026

repokitteh-read-only bot assigned markdroth Jan 15, 2026

bellatoris force-pushed the doogie/redis-zone-aware-routing branch 2 times, most recently from 84f9f19 to b7b0088 Compare January 15, 2026 07:57

bellatoris force-pushed the doogie/redis-zone-aware-routing branch from b7b0088 to 085d27f Compare January 15, 2026 07:59

nezdolik self-assigned this Jan 16, 2026

nezdolik reviewed Jan 26, 2026

View reviewed changes

markdroth reviewed Jan 28, 2026

View reviewed changes

api/envoy/extensions/filters/network/redis_proxy/v3/redis_proxy.proto Outdated Show resolved Hide resolved

bellatoris added 2 commits January 28, 2026 21:27

merge main

0532e02

repokitteh-read-only bot removed the api label Jan 28, 2026

bellatoris force-pushed the doogie/redis-zone-aware-routing branch 9 times, most recently from fd233b4 to 2b3aa82 Compare January 29, 2026 13:11

bellatoris force-pushed the doogie/redis-zone-aware-routing branch 2 times, most recently from 2db9fa9 to 186289b Compare January 29, 2026 15:39

repokitteh-read-only bot added the waiting label Mar 16, 2026

bellatoris and others added 2 commits March 17, 2026 09:10

Merge remote-tracking branch 'upstream/main' into doogie/redis-zone-a…

a02529d

…ware-routing

repokitteh-read-only bot removed the waiting label Mar 17, 2026

bellatoris requested a review from nezdolik March 17, 2026 03:28

Merge remote-tracking branch 'upstream/main' into doogie/redis-zone-a…

5caf561

…ware-routing # Conflicts: # changelogs/current.yaml

bellatoris requested a review from markdroth March 17, 2026 04:51

nezdolik reviewed Mar 20, 2026

View reviewed changes

Merge remote-tracking branch 'upstream/main' into worktree-pr43012-re…

c944320

…view-fixes

Address PR envoyproxy#43012 review comments from nezdolik (Mar 20)

13f2bef

- Switch to std::make_unique in RedisHost::create() by making constructor public - Return const unique_ptr& instead of raw pointer from replicasInZone() Signed-off-by: Doogie Min <doogie.min@sendbird.com>

bellatoris force-pushed the doogie/redis-zone-aware-routing branch from 5cd4e9b to 13f2bef Compare March 20, 2026 17:39

bellatoris requested a review from nezdolik March 20, 2026 18:02

gemini-code-assist bot reviewed Mar 23, 2026

View reviewed changes

bellatoris added 3 commits March 24, 2026 10:42

Merge upstream/main

4970982

fix: clang-format onZoneResponse parameter line

94f0de7

Signed-off-by: Doogie Min <doogie.min@sendbird.com>

bellatoris force-pushed the doogie/redis-zone-aware-routing branch from 448cfc5 to 94f0de7 Compare March 24, 2026 02:19

bellatoris requested review from agrawroh, jwendell and phlax as code owners March 24, 2026 02:19

revert: remove accidentally pushed OrbStack docker-compose.yml patch

d2c3d80

Signed-off-by: Doogie Min <doogie.min@sendbird.com>

Merge upstream/main

86eab22

Conversation

bellatoris commented Jan 15, 2026

Uh oh!

repokitteh-read-only bot commented Jan 15, 2026

Uh oh!

repokitteh-read-only bot commented Jan 15, 2026

Uh oh!

nezdolik left a comment

Choose a reason for hiding this comment

Uh oh!

nezdolik Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik commented Jan 26, 2026

Uh oh!

Uh oh!

markdroth commented Jan 28, 2026

Uh oh!

nezdolik commented Mar 16, 2026

Uh oh!

bellatoris commented Mar 17, 2026

Uh oh!

nezdolik left a comment

Choose a reason for hiding this comment

Uh oh!

nezdolik Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nezdolik Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bellatoris commented Mar 20, 2026

Uh oh!

nezdolik commented Mar 23, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

bellatoris Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

nezdolik commented Mar 23, 2026

Uh oh!

bellatoris commented Mar 24, 2026

Uh oh!

nezdolik commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nezdolik Mar 20, 2026 •

edited

Loading

nezdolik Mar 20, 2026 •

edited

Loading