apache / apache/apisix

feat: As a user, I want to the load balancer to support subset matching, so that I can quickly setup multiple service lanes

Open
#12,487 4 comments 0 reactions 0 assignees View on GitHub
discuss enhancement
Dominant language
Lua
Stars
17.1k
Forks
2.9k
Avg merge
3d 16h
Merged PRs (30d)
63

Description

### Description

As a user, I want to the load balancer to support subset matching, so that I can quickly setup multiple service lanes

This feature can be considered a simplified version of Envoy's subsets (https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/subsets).

After discovery retrieves the node list from the registry, the load balancing algorithm partitions the node list into subsets based on configured metadata keys. The requester can include a specific header (such as X-Env) or a set of headers in the request. If their values match the registered metadata, the corresponding subset will be used.

This is essential for microservice testing, and is actually part of implementing service swimlanes. I've previously implemented a tag-based subset algorithm in Kitex (ByteDance's microservice framework) (https://github.com/kitex-contrib/loadbalance-tagging/blob/main/tagging.go), and at my current employer, I've implemented a client-side load balancing algorithm based on grpc-go that's closer to Envoy subset (because our online service links are extremely long and latency-sensitive, we can't use Envoy proxies and instead use a fat client approach). However, we now need to implement swimlane splitting from the gateway.

This is our ideal swimlane diagram
![Image](https://github.com/user-attachments/assets/d4bad749-17dd-4aa2-94b9-1868806cb021)

However, the complete Envoy subset strategy is very complex, so we simplified it when implementing it. This is our final proto schema, it's enough.
```protobuf
message Subset {
enum LbSubsetFallbackPolicy {
NO_FALLBACK = 0;
ANY_ENDPOINT = 1;
DEFAULT_SUBSET = 2;
}
message LbSubsetSelector {
repeated string keys = 1;
}
LbSubsetFallbackPolicy fallback_policy = 1;
google.protobuf.Struct default_subset = 2;
repeated LbSubsetSelector subset_selectors = 3;

string header_prefix = 254;
string type = 255;
}
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing APISIX's discovery and load-balancing paths, then compare the proposed Subset schema with Envoy's subset-matching reference. Trace how discovered node metadata and request headers would connect to the selectors and fallback policies. Done means subset selection, header-prefix handling, and all three fallback policies are implemented and covered by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.