Traefik Sticky Sessions: How to Configure Cookie-Based Load Balancing

Traefik supports sticky sessions by injecting a configurable cookie into the first response that binds subsequent client requests to the same backend server using a SHA-256 hash of the handler name.

Sticky sessions ensure that requests from the same client consistently reach the same backend server, which is critical for stateful applications. In the traefik/traefik repository, this feature is implemented through cookie-based session affinity that works across all built-in load balancing algorithms.

How Traefik Sticky Sessions Work

Traefik implements sticky sessions by attaching a cookie to the first response sent to a client. According to the source code in pkg/server/service/loadbalancer/sticky.go, the cookie value stores a SHA-256 hash of the backend handler name, enabling the load balancer to route subsequent requests without exposing internal server identifiers.

When a client sends subsequent requests with this cookie, the sticky load-balancer (supporting wrr, p2c, or leasttime algorithms) looks up the stored handler name using the cookie value. If the backend remains healthy, the request routes to the same server. If the backend becomes unhealthy, Traefik falls back to normal load balancing and rewrites the cookie to point to the new server.

Configuring Cookie-Based Load Balancing

You can enable sticky sessions via the dynamic configuration file or provider-specific labels and annotations. All cookie attributes—including name, domain, path, secure, httpOnly, sameSite, and maxAge—are customizable through the dynamic.Cookie struct defined in pkg/config/dynamic/http_config.go.

File Provider (YAML)

Enable sticky sessions with default cookie settings:

http:
  services:
    my-service:
      loadBalancer:
        sticky:
          cookie: {}
        servers:
          - url: "http://127.0.0.1:8081"
          - url: "http://127.0.0.1:8082"

Customize cookie attributes for production environments:

http:
  services:
    my-service:
      loadBalancer:
        sticky:
          cookie:
            name: my_sticky_cookie
            secure: true
            httpOnly: true
            sameSite: none
            domain: example.com
            maxAge: 3600

Docker and Docker Swarm Labels

Configure sticky sessions on a Docker Swarm service using labels:

docker service create \
  --label "traefik.http.services.myservice.loadbalancer.sticky.cookie=true" \
  --label "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=my_sticky_cookie" \
  --label "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true" \
  myimage

The Swarm provider parses these labels and translates them to the same dynamic.Sticky configuration used by the file provider.

Kubernetes Ingress Annotations

Enable sticky sessions on a Kubernetes Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    traefik.ingress.kubernetes.io/service.sticky.cookie: "true"
    traefik.ingress.kubernetes.io/service.sticky.cookie.name: "my_sticky_cookie"
    traefik.ingress.kubernetes.io/service.sticky.cookie.secure: "true"
spec:
  rules:
  - http:
      paths:
      - path: /
        backend:
          service:
            name: my-service
            port:
              number: 80

Verifying Sticky Sessions

Test sticky session behavior using curl to observe cookie setting and reuse:

# First request – Traefik sets the sticky cookie

curl -i http://localhost:8000

# Subsequent requests – include the cookie to remain on the same backend

curl -b "my_sticky_cookie=abc123" http://localhost:8000

The StickyHandler in pkg/server/service/loadbalancer/sticky.go reads the Cookie header to look up the correct backend handler.

Implementation Details

The sticky session feature is implemented across several key files in the traefik/traefik repository:

• pkg/server/service/loadbalancer/sticky.go: Contains the StickyHandler struct and methods for cookie generation, SHA-256 hashing of handler names, and request routing logic.
• pkg/config/dynamic/http_config.go: Defines the Sticky and Cookie configuration structs used by the service manager.
• pkg/server/service/service.go: Applies sticky configuration when creating load balancer instances according to the dynamic configuration schema.

Summary

• Traefik supports sticky sessions via cookie-based session affinity across all load balancing algorithms (wrr, p2c, leasttime).
• Enable stickiness by adding a sticky.cookie configuration block in your dynamic configuration or using provider-specific labels/annotations.
• Cookie attributes—including name, secure, httpOnly, sameSite, domain, and maxAge—are fully customizable.
• The implementation uses SHA-256 hashing to map cookie values to backend handlers, with automatic fallback to normal load balancing if the sticky backend becomes unhealthy.

Frequently Asked Questions

What load balancing algorithms support sticky sessions in Traefik?

All built-in load balancing algorithms support sticky sessions, including Weighted Round Robin (wrr), Power of Two Choices (p2c), and Least Time (leasttime). The sticky handler wraps the underlying balancer in pkg/server/service/loadbalancer/sticky.go, ensuring session affinity works regardless of the distribution strategy.

What happens if the sticky backend becomes unhealthy?

If the backend server identified by the sticky cookie becomes unhealthy or is removed from the pool, Traefik automatically falls back to normal load balancing. The request is routed to a new healthy backend, and the cookie is rewritten to point to the new server, ensuring continuous service without manual intervention.

Can I customize the cookie name and security flags?

Yes. All cookie attributes are configurable through the sticky.cookie options. You can set a custom name, enable secure and httpOnly flags, specify a domain and path, set sameSite policies (none, lax, strict), and define a maxAge in seconds. These settings map directly to the dynamic.Cookie struct in the Traefik source code.

Does Traefik support IP hash-based sticky sessions?

No. Traefik does not implement IP hash-based session affinity. Instead, it uses cookie-based stickiness where a cookie is set on the client containing a SHA-256 hash of the backend handler name. This approach is more reliable than IP hashing in environments where clients may change IP addresses frequently, such as behind NAT gateways or on mobile networks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}