Using Sticky Session Cookies

This section describes how to use sticky session cookies for HTTP routes.

Using sticky session cookies

By default, the Apcera Platform router load balances HTTP requests for a given job route equally among instances that share that route; there is no guarantee that a client will connect to the same back-end job instance on subsequent requests. You can optionally configure a job so that requests are always routed to the same back-end job instance using "sticky session cookies".

To use sticky session cookies, you need to do the following:

  • Update your job definition with the name(s) of the sticky session cookie(s) you want to indicate a sticky HTTP session.
  • Modify your job's HTTP response handler to include a Set-Cookie header that sets a cookie whose name matches a sticky session cookie set on the job definition.

You use the --sticky-session-cookies parameter with the app create or app update commands to specify a job's sticky session cookie names. For example, the following sets two sticky session cookies, COOKIE_1 and COOKIE_2, on the specified job:

apc app update my-sticky-app \
--sticky-session-cookies=COOKIE_1,COOKIE_2 \
--routes http://myroute.example.com

Modify application response header

Your application's HTTP response must include a Set-Cookie response header that sets a cookie that matches one of the job's specified sticky session cookie names, for example:

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=value; expires=Fri, 04-Aug-2017 19:48:43 GMT; Max-Age=3600

The Apcera router notices the presence of a valid sticky session cookie in your app's response and adds another cookie named Continuum-LB cookie to the HTTP response before sending it on to the requesting client, for example:

Set-Cookie: JSESSIONID=value; expires=Fri, 04-Aug-2017 19:49:58 GMT; Max-Age=3600
Set-Cookie: Continuum-LB=qCaIiDEipmiKPxJVEsWf-WF-BUUvOUZ9oOPvGgvGPv_Aeed49xsGBPci5QePtzMp6z4_gzpQlOGsqreZZ-hGt7yenVcgeSaLozkY2FGFA-CIYgTyHTImhV2fyKJ8Ve-T; expires=Fri, 04-Aug-2017 19:49:58 GMT; Max-Age=3600

The Continuum-LB cookie's value is a encrypted string that identifies the job instance that handled the initial client request. (Cookie encryption requires that your cluster is configured with the proper encryption keys). Subsequent client requests that include the same Continuum-LB cookie, and the original sticky session cookie, will be routed to the same job instance. The sticky session cookie demo application demonstrates using sticky session cookies in a browser application.

To remove all sticky session cookies from a job pass the --no-sticky-session-cookies parameter to apc app update, for example:

apc app update my-sticky-app --no-sticky-session-cookies