feat: As a user, I want to the load balancer to support subset matching, so that I can quickly setup multiple service lanes
- 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

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
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