Stateful session
The stateful session filter overrides the upstream host based on extensible session state and updates the session state based on the final selected upstream host. The override takes precedence over the result of load balancing. This filter implements session stickiness without relying on a hash-based load balancer.
By extending the session state, this filter also allows more flexible control over load balancing results.
Note
Stateful sessions can result in imbalanced load across upstreams and allow external actors to direct requests to specific upstream hosts. Operators should carefully consider the security and reliability implications of stateful sessions before enabling this feature.
Overview
Session stickiness allows requests belonging to the same session to be consistently routed to a specific upstream host.
HTTP session stickiness in Envoy is generally achieved through hash-based load balancing. The stickiness of hash-based sessions is considered ‘weak’ because the upstream host may change when the host set changes. This filter implements ‘strong’ stickiness. It is intended to handle the following cases:
The case where more stable session stickiness is required. For example, when a host is marked as degraded but it is desirable to continue routing requests for existing sessions to that host.
The case where a non-hash-based load balancer (Random, Round Robin, etc.) is used and session stickiness is still required. If stateful sessions are enabled in this case, requests for new sessions will be routed to the corresponding upstream host based on the result of load balancing. Requests belonging to existing sessions will be routed to the session’s upstream host.
Configuration
This filter should be configured with the type URL
type.googleapis.com/envoy.extensions.filters.http.stateful_session.v3.StatefulSession.
How it works
The most important configuration for this filter is an extensible session state.
While processing the request, the stateful session filter will search for the corresponding session and host based on the request. The results of the search will be used to influence the final load balancing results.
If no existing session is found, the filter will create a session to store the selected upstream host. Please note that the session here is an abstract concept. The details of the storage are based on the session state implementation.
Examples
Currently, cookie-based session state and header-based session state are supported. The following shows a cookie-based configuration.
28 cluster: service1
29
30 http_filters:
31 - name: envoy.filters.http.stateful_session
32 typed_config:
33 "@type": type.googleapis.com/envoy.extensions.filters.http.stateful_session.v3.StatefulSession
34 session_state:
35 name: envoy.http.stateful_session.cookie
36 typed_config:
37 "@type": type.googleapis.com/envoy.extensions.http.stateful_session.cookie.v3.CookieBasedSessionState
38 cookie:
39 name: global-session-cookie
40 path: /path
41 ttl: 120s
42 - name: envoy.filters.http.router
43 typed_config:
44 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
In the above configuration, the cookie-based session state obtains the overridden host of the current session
from the cookie named global-session-cookie and, if the corresponding host exists in the upstream cluster, the
request will be routed to that host.
If there is no valid cookie, the load balancer will choose a new upstream host. When responding, the address
of the selected upstream host will be stored in the cookie named global-session-cookie.
A similar example for a header-based configuration is:
28 cluster: service1
29
30 http_filters:
31 - name: envoy.filters.http.stateful_session
32 typed_config:
33 "@type": type.googleapis.com/envoy.extensions.filters.http.stateful_session.v3.StatefulSession
34 session_state:
35 name: envoy.http.stateful_session.header
36 typed_config:
37 "@type": type.googleapis.com/envoy.extensions.http.stateful_session.header.v3.HeaderBasedSessionState
38 name: session-header
39 - name: envoy.filters.http.router
40 typed_config:
41 "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
Note
The header-based implementation assumes that a client will use the last supplied value for the session header and will pass it with every subsequent request.
StatefulSessionPerRoute should be used if path match is required.
Statistics
This filter outputs statistics in the
http.<stat_prefix>.stateful_session. namespace. The stat prefix
comes from the owning HTTP connection manager.
When stat_prefix is not configured on the filter, no statistics are emitted.
If stat_prefix is
configured on the filter, an additional segment is inserted after stateful_session to allow
distinguishing statistics from multiple instances, e.g. http.<stat_prefix>.stateful_session.my_prefix.routed.
Note
Per-route configuration overrides do not support statistics and will not emit statistics even if stat_prefix is set in the per-route configuration.
The following statistics are supported:
Name |
Type |
Description |
|---|---|---|
routed |
Counter |
Total requests where a stateful session override was attempted and successfully applied and the selected upstream matched the requested session destination. |
failed_open |
Counter |
Total requests where an override was attempted but the requested destination
was unavailable and the request proceeded using default load balancing ( |
failed_closed |
Counter |
Total requests where an override was attempted but the requested
destination was unavailable and the request was fail-closed with a |