Session persistence

Session persistence means that the load balancer routes a client to the same backend server once they have been routed to that server once. It avoids the overhead of re-establishing a client’s state on a new server with each request, since the same server is always chosen. Often, it is optimal to avoid session persistence altogether by building your services to be stateless, such as by storing state off of the application servers in a shared database. However, for certain applications this is not possible.

Support for two forms of session persistence exists:

• Persistence based on an HTTP cookie. This option is only available when mode http is set in the backend.
• Persistence based on the client’s IP address. This option is available with both mode http and mode tcp.

Cookie-based persistence Jump to heading #

To enable session persistence based on an HTTP cookie:

• Add the cookie directive to your backend section. It instructs the load balancer to place a cookie in the client’s browser, which it will use to remember which server the client was routed to before.

• Also, place a cookie argument on each server line. This sets the value that will be stored in the cookie and it should be unique for each server.

haproxy
backend servers
  mode http
  cookie SERVER_USED insert indirect nocache
  server s1 192.168.0.10:80 check cookie s1
  server s2 192.168.0.11:80 check cookie s2

haproxy
backend servers
  mode http
  cookie SERVER_USED insert indirect nocache
  server s1 192.168.0.10:80 check cookie s1
  server s2 192.168.0.11:80 check cookie s2

Set a dynamic cookie key Jump to heading #

Instead of specifying cookie values explicitly via the cookie argument on a server line, you can configure the backend to dynamically generate cookie values. The value of the cookie will be the hash of the server’s IP address, port, and a secret key you provide.

To enable dynamic generation of server cookies, use the cookie directive’s dynamic argument. Specify the dynamic cookie key using the dynamic-cookie-key directive.

haproxy
backend servers
  mode http
  cookie SERVER_USED insert indirect nocache dynamic
  dynamic-cookie-key secretphrase123
  server s1 192.168.0.10:80 check
  server s2 192.168.0.11:80 check

haproxy
backend servers
  mode http
  cookie SERVER_USED insert indirect nocache dynamic
  dynamic-cookie-key secretphrase123
  server s1 192.168.0.10:80 check
  server s2 192.168.0.11:80 check

If you set the cookie argument on the server line, this cookie value will take precedence over the dynamic cookie value.

IP-based persistence Jump to heading #

To enable session persistence based on the client’s IP address:

• Add a stick-table line to your backend section. It creates an in-memory storage to hold client IP addresses. Entries in the stick table expire after 30 minutes if not used.
• Add the line stick on src, which stores a client’s IP address in the stick table and associates it with the server to which they were routed. On subsequent visits, they will use this same server.

haproxy
backend servers
  mode tcp
  stick-table type ip  size 1m  expire 30m
  stick on src
  server s1 192.168.0.10:80 check
  server s2 192.168.0.11:80 check

haproxy
backend servers
  mode tcp
  stick-table type ip  size 1m  expire 30m
  stick on src
  server s1 192.168.0.10:80 check
  server s2 192.168.0.11:80 check

IP-based persistence can be less precise than cookie-based persistence because multiple clients may originate from the same IP address. The only side effect of this is persisting more clients to the same server.

See also Jump to heading #

• Stick tables concepts
• cookie
• dynamic-cookie-key
• stick on