Use persistent sessions

This topic describes how to publish a service with a proxy that is configured for persistent sessions using either cookies or IP hashing. Persistent sessions are also known as sticky sessions.

Configure persistent sessions using cookies

  1. Create an overlay network to isolate and secure service traffic:

    docker network create -d overlay demo
    

    Example output:

    1se1glh749q1i4pw0kf26mfx5
    
  2. Create a service with the persistent session cookie:

    docker service create \
    --name demo \
    --network demo \
    --detach=false \
    --replicas=5 \
    --label com.docker.lb.hosts=demo.local \
    --label com.docker.lb.sticky_session_cookie=session \
    --label com.docker.lb.port=8080 \
    --env METADATA="demo-sticky" \
    nmsteph/docker-demo
    

    Interlock detects when the service is available and publishes it.

  3. After tasks are running and the proxy service is updated, the application is configured to use persistent sessions and is available at http://demo.local:

    curl -vs -c cookie.txt -b cookie.txt -H "Host: demo.local" http://127.0.0.1/ping
    

    Example output:

    *   Trying 127.0.0.1...
    * TCP_NODELAY set
    * Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
    > GET /ping HTTP/1.1
    > Host: demo.local
    > User-Agent: curl/7.54.0
    > Accept: */*
    > Cookie: session=1510171444496686286
    >
    < HTTP/1.1 200 OK
    < Server: nginx/1.13.6
    < Date: Wed, 08 Nov 2017 20:04:36 GMT
    < Content-Type: text/plain; charset=utf-8
    < Content-Length: 117
    < Connection: keep-alive
    * Replaced cookie session="1510171444496686286" for domain demo.local, path /, expire 0
    < Set-Cookie: session=1510171444496686286
    < x-request-id: 3014728b429320f786728401a83246b8
    < x-proxy-id: eae36bf0a3dc
    < x-server-info: interlock/2.0.0-development (147ff2b1) linux/amd64
    < x-upstream-addr: 10.0.2.5:8080
    < x-upstream-response-time: 1510171476.948
    <
    {"instance":"9c67a943ffce","version":"0.1","metadata":"demo-sticky","request_id":"3014728b429320f786728401a83246b8"}
    

    The curl command stores Set-Cookie from the application and sends it with subsequent requests, which are pinned to the same instance. If you make multiple requests, the same x-upstream-addr is present in each.

Configure persistent sessions using IP hashing

Using client IP hashing to configure persistent sessions is not as flexible or consistent as using cookies but it enables workarounds for applications that cannot use the other method. To use IP hashing, you must reconfigure Interlock proxy to use host mode networking, because the default ingress networking mode uses SNAT, which obscures client IP addresses.

  1. Create an overlay network to isolate and secure service traffic:

    docker network create -d overlay demo
    

    Example output:

    1se1glh749q1i4pw0kf26mfx5
    
  2. Create a service using IP hashing:

    docker service create \
    --name demo \
    --network demo \
    --detach=false \
    --replicas=5 \
    --label com.docker.lb.hosts=demo.local \
    --label com.docker.lb.port=8080 \
    --label com.docker.lb.ip_hash=true \
    --env METADATA="demo-sticky" \
    nmsteph/docker-demo
    

    Interlock detects when the service is available and publishes it.

  3. After tasks are running and the proxy service is updated, the application is configured to use persistent sessions and is available at http://demo.local:

    curl -vs -H "Host: demo.local" http://127.0.0.1/ping
    

    Example output:

    *   Trying 127.0.0.1...
    * TCP_NODELAY set
    * Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
    > GET /ping HTTP/1.1
    > Host: demo.local
    > User-Agent: curl/7.54.0
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < Server: nginx/1.13.6
    < Date: Wed, 08 Nov 2017 20:04:36 GMT
    < Content-Type: text/plain; charset=utf-8
    < Content-Length: 117
    < Connection: keep-alive
    < x-request-id: 3014728b429320f786728401a83246b8
    < x-proxy-id: eae36bf0a3dc
    < x-server-info: interlock/2.0.0-development (147ff2b1) linux/amd64
    < x-upstream-addr: 10.0.2.5:8080
    < x-upstream-response-time: 1510171476.948
    <
    {"instance":"9c67a943ffce","version":"0.1","metadata":"demo-sticky","request_id":"3014728b429320f786728401a83246b8"}
    
  4. Optional. Add additional replicas:

    docker service scale demo=10
    

    Note

    IP hashing for extensions creates a new upstream address when scaling replicas because the proxy uses the new set of replicas to determine where to pin the requests. When the upstreams are determined, a new “sticky” back end is selected as the dedicated upstream.