Session affinity allows you to route requests for a particular session to the same backend service instance that served the initial request. This setup is particularly useful if you have a backend service that performs expensive operations and caches the output or data for subsequent requests. With session affinity, you make sure that the expensive operation is performed once and that subsequent requests can be served from the backend’s cache, which can significantly improve operational cost and response times for your clients.
Gloo Gateway allows you to set up soft session affinity between a client and a backend service by using the Ringhash or Maglev consistent hashing algorithm. The hashing algorithm uses a property of the request, such as a cookie, header, or source IP address, and hashes this property with the address of a backend service instance that served the initial request. In subsequent requests, as long as the client sends the same request property, the request is routed to the same backend service instance.
Request properties are configured in the loadBalancer.hashPolicies section of a BackendConfigPolicy. The header, cookie, and sourceIP hash policies are mutually exclusive, in that a request can only have one property that the algorithm uses for hashing. However, you can define multiple different hash policies within one BackendConfigPolicy by using the terminal field for each hash policy. If a policy has the terminal: true setting and the policy is matched, any subsequent hash policies are skipped. This field is useful for defining fallback policies, and limiting the amount of time spent generating hash keys.
info
Consistent hashing is less reliable than a “strong” or “sticky” session affinity implementation, such as session persistence, in which the backend service is encoded in a cookie or header and affinity can be maintained for as long as the backend service is available. With consistent hashing, affinity might be lost when an instance is added or removed from the backend service’s pool, or if the gateway proxy restarts. To set up strong stickiness, see the Session persistence docs.
Ringhash allows you to tune the ring size to balance memory usage vs load distribution precision. This way, you get more fine-grained control over how traffic is distributed across endpoint. However, this configurability might come at a performance cost, depending on your setup. To learn more about Ringhash, see the Envoy documentation.
Create a BackendConfigPolicy that uses the request property of your choice.
Create a consistent hash by using a specific request header.
Review the following table to understand this configuration.
Setting
Description
ringHash.minimumRingSize
The minimum ring size. The size of the ring determines the number of hashes that can be assigned for each host and placed on the ring. The ring number is divided by the number of hosts that serve the request. For example, if you have 2 hosts and the minimum ring size is 1000, each host gets approximately 500 hashes in the ring. When a request is received, the request is assigned a hash in the ring, and therefore assigned to a particular host. Generally speaking, the larger the ring size is, the better distribution between hosts can be achieved. If not set, the minimum ring size defaults to 1024.
ringHash.maximumRingSize
The maximum ring size. If not set, the maximum ring size defaults to 8 million.
useHostnameForHashing
If set to true, the gateway proxy uses the hostname as the key to consistently hash to a backend host. If not set, defaults to using the resolved address of the hostname as the key.
header.name
The expected header name to create the hash with.
terminal
If you define multiple hashPolicies in one BackendConfigPolicy, you can use the terminal field to determine which policy is the priority. For example, in this policy, the x-user-id header has the terminal: true setting. This indicates that if the request has the x-user-id header, any subsequent policies (such as the x-session-id header in this example) are skipped. This field is useful for defining fallback policies, and limiting the amount of time spent generating hash keys.
closeConnectionsOnHostSetChange
If set to true, the proxy drains all existing connections to a backend host whenever hosts are added or removed for a backend pool.
Review the following table to understand this configuration.
Setting
Description
ringHash.minimumRingSize
The minimum ring size. The size of the ring determines the number of hashes that can be assigned for each host and placed on the ring. The ring number is divided by the number of hosts that serve the request. For example, if you have 2 hosts and the minimum ring size is 1000, each host gets approximately 500 hashes in the ring. When a request is received, the request is assigned a hash in the ring, and therefore assigned to a particular host. Generally speaking, the larger the ring size is, the better distribution between hosts can be achieved. If not set, the minimum ring size defaults to 1024.
ringHash.maximumRingSize
The maximum ring size. If not set, the maximum ring size defaults to 8 million.
cookie.name
The expected cookie name to create the hash with. In this example, the cookie is named session-id.
cookie.path
The name of the path for the cookie, such as /api in this example.
cookie.ttl
If the cookie is not present, a cookie with this duration of time for validity is generated, such as 30 minutes in this example.
cookie.attributes
Define additional attributes for an HTTP cookie. This example sets three additional attirbutes: httpOnly: true, secure: true, and sameSite: Strict.
terminal
If you define multiple hashPolicies in one BackendConfigPolicy, you can use the terminal: true setting to indicate the priority policy.
Create a consistent hash by using the source IP address.
The minimum ring size. The size of the ring determines the number of hashes that can be assigned for each host and placed on the ring. The ring number is divided by the number of hosts that serve the request. For example, if you have 2 hosts and the minimum ring size is 1000, each host gets approximately 500 hashes in the ring. When a request is received, the request is assigned a hash in the ring, and therefore assigned to a particular host. Generally speaking, the larger the ring size is, the better distribution between hosts can be achieved. If not set, the minimum ring size defaults to 1024.
ringHash.maximumRingSize
The maximum ring size. If not set, the maximum ring size defaults to 8 million.
sourceIP
Hash based on the source IP address of the request. No further configuration is required.
terminal
If you define multiple hashPolicies in one BackendConfigPolicy, you can use the terminal: true setting to indicate the priority policy.
With Maglev, you use a fixed lookup table of 65,357 entries that is optimized for fast request routing with deterministic performance. This option is well-suited for general-purpose workloads that do not require custom tuning. For more information, see the Envoy docs.
Create a BackendConfigPolicy that uses the request property of your choice.
Review the following table to understand this configuration.
Setting
Description
header.name
The expected header name to create the hash with.
terminal
If you define multiple hashPolicies in one BackendConfigPolicy, you can use the terminal field to determine which policy is the priority. For example, in this policy, the x-user-id header has the terminal: true setting. This indicates that if the request has the x-user-id header, any subsequent policies (such as the x-session-id header in this example) are skipped. This field is useful for defining fallback policies, and limiting the amount of time spent generating hash keys.
useHostnameForHashing
If set to true, the gateway proxy uses the hostname as the key to consistently hash to a backend host. If not set, defaults to using the resolved address of the hostname as the key.
closeConnectionsOnHostSetChange
If set to true, the proxy drains all existing connections to a backend host whenever hosts are added or removed for a backend pool.
Verify that another instance of the httpbin app is created.
kubectl get pods -n httpbin
Example output:
NAME READY STATUS RESTARTS AGE
httpbin-8d557795f-86hzg 3/3 Running 0 54s
httpbin-8d557795f-h8ks9 3/3 Running 0 26m
Test consistent hashing by sending multiple requests to the httpbin app and verifying that all requests are served by the same backend instance. Note that the verification steps vary depending on the hashing policy that you defined.
Headers:
for i in {1..10}; do curl -vik http://$INGRESS_GW_ADDRESS:8080/headers \
-H "x-user-id: me" \
-H "host: www.example.com"; done
Source IP address:
for i in {1..10}; do curl -vik http://$INGRESS_GW_ADDRESS:8080/headers \
-H "host: www.example.com"; done
Cookies:
Send a request to the httpbin app and verify that you get back a set-cookie header with a session-id.