Stateful Applications

In some cases, applications protected by IBM Application Gateway may need to maintain state. That is, during a client session all requests for a particular resource server need to be routed to the same server.

For example, consider the following configuration where the /accounting resource server is a legacy application available on two servers:

resource_servers:
  - path: /accounting
    servers:
      - server: acc1.demo.com
        port:   9443
        ...
      - server: acc2.demo.com
        port:   9443
        ...
    ...

Under normal operation, the load sharing algorithm within IAG may direct client requests in the same session to either acc1.demo.com or acc2.demo.com. By default, IAG balances server load by distributing requests across all available replicated servers. IAG uses a "least-busy" algorithm. This algorithm directs each new request to the server with the fewest connections already in progress.

To prevent this from happening, the resource server can be defined as stateful. When IAG processes a request for a stateful resource server, IAG ensures that all subsequent requests from that client during that session are forwarded to the same server, and not distributed among the other replicated back-end servers according to the load balancing rules.

Configuring Stateful Applications

To define an application as stateful, set the resource_servers[]/stateful parameter to true.

resource_servers:
  - path: /accounting
    servers:
      - server: acc1.demo.com
        port:   9443
        ...
      - server: acc2.demo.com
        port:   9443
        ...
    ...
    stateful: true

When a request is made to a stateful resource server, the client will receive a new cookie named PD_STATEFUL_<server uuid> with a value containing the resource server path or virtual host. This cookie is the mechanism used by IAG to determine which server the request should be handled by. The <server uuid> is randomly generated by IAG on start up, but can be statically set using the server/uuid field.

Handling Stateful Applications Across Multiple Instances

If there are multiple instances of IAG protecting a stateful application with the same set of servers, an additional step must be taken to ensure that all IAG instances can correctly route the client requests. As <server uuid> is used to track which server should be used, all IAG instances must be statically configured with the same UUIDs for each server.

For example, consider two instances of IAG (iag-1 and iag-2) with the following configuration:

resource_servers:
  - path: /accounting
    servers:
      - server: acc1.demo.com
        port:   9443
        ...
        uuid: 63629412-A012-44FF-8B9D-3A220FCDD2CE
      - server: acc2.demo.com
        port:   9443
        ...
        uuid: F7B507DA-BB62-43B1-A5A6-A06CF6591F39
    ...
    stateful: true

A new client makes a request for /accounting that is received by iag-1.
The load balancing algorithm in IAG decides that acc2.demo.com should handle this request.
A response is returned to the client containing a cookie indicating that acc2.ibm.com (F7B507DA-BB62-43B1-A5A6-A06CF6591F39) is the server that should be used. (PD_STATEFUL_F7B507DA-BB62-43B1-A5A6-A06CF6591F39=%2Faccounting)
The client makes another request for /accounting that is received by iag-2, this request includes the cookie received from iag-1.
iag-2 received the request and cookie indicating that F7B507DA-BB62-43B1-A5A6-A06CF6591F39 is the correct server, and selects acc2.demo.com to fulfill the request.