stickyheader

README

StickyHeader is a plugin for Traefik that enables sticky sessions based on headers.

Plugin created by nullxjx just made some adjustments to the original code to make it work with treafik external plugin system.

Introduction

Traefik uses cookies to implement sticky sessions, and by default, it doesn't support session persistence based on headers (such as IP Hash). However, some business scenarios require session persistence based on headers. For example, services like vllm with prefix-caching features may need to route requests from the same user to the same vllm pod, thereby improving the cache hit rate of the key-value (KV) cache in the GPU.

To address this, this plugin uses a local LRU cache to store the mapping between headers in requests and cookies set by Traefik. This allows Traefik’s cookie-based session persistence to be converted into header-based session persistence.

Installation via helm chart

experimental:
  plugins:
    stickyheader:
      moduleName: github.com/akierat/stickyheader
      version: v1.0.0

Usage in IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: stickyheader-route
spec:
  entryPoints:
    - web
    - websecure
  routes:
    - kind: Rule
      match: Host(`example.pl`) && PathPrefix(`/example`)
      middlewares:
        - name: stickyheader-middleware
      services:
        - name: backend-service
          port: 80
          sticky:
            cookie:
              name: session_cookie
  tls:
    secretName: ssl-secret

Usage in Middleware

---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: stickyheader-middleware
  namespace: dev-1
spec:
  plugin:
    stickyheader:
      cacheSize: 100
      headerName: X-Custom-Session
      cookieName: session_cookie

Usage

1. Since yaegi currently doesn't support Go modules, you need to download the repository's dependencies into your local vendor directory first:

   go mod tidy
   go mod download
   go mod vendor
   

2. Start the service:

   cd demo
   docker-compose up -d
   

   After executing the command, you should see in the Traefik logs that the plugin has loaded successfully:

   

   Additionally, you can see the route in the Traefik dashboard where the plugin has been successfully applied:

   

   

3. Test the header-based session persistence:

   bash req.sh
   

   Modify the X-USER-ID value in the header, and observe the response to see if it switches to a different whoami pod.

Limitations

Since the plugin uses a local LRU cache, it becomes a stateful service. Therefore, it cannot be used with multiple Traefik pod replicas (in a Kubernetes cluster, for example). If you need to use multiple Traefik pod replicas, you'll need to replace the LRU cache with a shared cache like Redis.

Partly workarround for multiple Traefik pod replicas inside Kubernetes cluster for svc

  sessionAffinity: ClientIP
  sessionAffinityConfig:
    clientIP:
      timeoutSeconds: 600

Documentation

Overview

Package stickyheader DO NOT MODIFY THIS! cookie.go is copied from net/http/cookie.go in go 1.23.0 or above, and modified a little bit. Since ParseSetCookie func is introduced in Go 1.23.0. See doc https://pkg.go.dev/net/http#ParseSetCookie Up to now(2024.11.30), https://github.com/traefik/yaegi (latest version is v0.16.1) only supports Go version 1.21 and 1.22 in this case, when using this func in yaegi, there will be a compile error: package http "net/http" has no symbol ParseSetCookie so, in order to use this func, we need to copy this file from net/http/cookie.go in Go 1.23.0 please remove it and directly use http.ParseSetCookie when yaegi supports Go 1.23.0

Index

• func IsPrint(s string) bool
• func IsTokenRune(r rune) bool
• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• func ParseSetCookie(line string) (*http.Cookie, error)
• func ToLower(s string) (lower string, ok bool)
• type Config
  • func CreateConfig() *Config
• type CookieManager
  • func (c *CookieManager) ServeHTTP(rw http.ResponseWriter, req *http.Request)

Functions

func IsPrint

func IsPrint(s string) bool

IsPrint returns whether s is ASCII and printable according to https://tools.ietf.org/html/rfc20#section-4.2.

func IsTokenRune

func IsTokenRune(r rune) bool

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

func ParseSetCookie

func ParseSetCookie(line string) (*http.Cookie, error)

ParseSetCookie parses a Set-Cookie header value and returns a cookie. It returns an error on syntax error.

func ToLower

func ToLower(s string) (lower string, ok bool)

ToLower returns the lowercase version of s if s is ASCII and printable.

Types

type Config

type Config struct {
	CacheSize  int    `json:"cacheSize,omitempty"`
	HeaderName string `json:"headerName,omitempty"`
	CookieName string `json:"cookieName,omitempty"`
}

Config the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type CookieManager

type CookieManager struct {
	Config *Config
	// contains filtered or unexported fields
}

func (*CookieManager) ServeHTTP

func (c *CookieManager) ServeHTTP(rw http.ResponseWriter, req *http.Request)