Support Multiple ConsistentHash Policies

[Inode1]

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

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

[arkodg]

we recently added support for hashing based off multiple headers https://github.com/envoyproxy/gateway/pull/7198/changes
we could do the same for Cookie

this should be adequate if youre looking for hashing based off multiple values

the per policy approach adds more fine grained knobs to control hashing per tuple, is this needed ?
from the docs all hashes generated by all list entries are taken into account, unless terminal is set which short circuits if hash is generated, im guessing this is the limitation today ?

[Inode1]

the per policy approach adds more fine grained knobs to control hashing per tuple, is this needed ? from the docs all hashes generated by all list entries are taken into account, unless terminal is set which short circuits if hash is generated, im guessing this is the limitation today ?

Yes, exactly. The same limitation applies to mixing different source types (cookies + headers) as well.

[arkodg]

sure +1

[arkodg]

will bring this up in the community meeting to make sure everyone votes