envoyproxy / envoyproxy/gateway

Support Multiple ConsistentHash Policies

Open
#8,270 10 comments 0 reactions 1 assignee Claimed by @Inode1 View on GitHub
area/api stale
Dominant language
Go
Stars
3k
Forks
864
Avg merge
2d 2h
Merged PRs (30d)
140

Description

*Description*:
Enhance BackendTrafficPolicy.spec.loadBalancer.consistentHash to support multiple ordered hash policies, aligning with Envoy’s native hash_policy[] behavior.
Currently, only a single hash policy can be configured via:
```
consistentHash:
type: SourceIP | Header | Cookie
header: {}
cookie: {}
tableSize:
```

This limits advanced stickiness and fallback hashing scenarios supported by Envoy.
This prevents:

1. Fallback hashing (e.g., Header → Cookie → SourceIP)
2. More advanced session affinity strategies
3. Parity with Envoy capabilities
4. Smooth migration of existing Envoy configs to Envoy Gateway

**Proposed**

Replace the single-policy model with an ordered list of policies, while keeping backward
```
spec:
loadBalancer:
type: ConsistentHash
consistentHash:
tableSize: 65537
policies:
- type: Header
header:
name: x-user-id
- type: Cookie
cookie:
name: session_id
- type: SourceIP
```

```
type ConsistentHash struct {
// TableSize for ring/maglev hashing
TableSize *int

// Policies defines ordered hash policies.
Policies []HashPolicy `json:"policies,omitempty"`

// Deprecated: use Policies instead.
Type *ConsistentHashType
Header *HeaderHash
Cookie *CookieHash
}

type HashPolicy struct {
Type ConsistentHashType `json:"type"`

Header *HeaderHash `json:"header,omitempty"`
Cookie *CookieHash `json:"cookie,omitempty"`

// Optional, matches Envoy semantics
Terminal *bool `json:"terminal,omitempty"`
}
```

**Semantics**

1. Policies evaluated in order
2. First policy that produces a hash wins
3. Optional terminal field to match Envoy behavior
4. If none produce a hash → fallback to normal LB behavior

**Backward Compatibility**

Suggested approach:

Keep existing fields (type, header, cookie) but mark them deprecated
Introduce new policies[] field

Logic:

If policies is set → use it
Else → convert legacy fields into a single-item policy list
Add validation to prevent mixing legacy and new fields

[optional *Relevant Links*:]

https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-routeaction
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.