Bloomreach Experience Manager Load Balancing Requirements

Introduction

Goal

Learn how to configure server affinity required to run Bloomreach Experience Manager behind a load balancer.

Background

Running Bloomreach Experience Manager behind a load balancer requires server affinity to be configured in the load balancer.

The Experience manager app provides preview access to and management for the delivery tier (the Site application(s) serving the Delivery API and/or Freemarker-based frontend).

To be able to do so it is required that both the CMS and Site web applications are hosted on the same appllication server (Tomcat) and that the client access is coordinated to be served from the same backend application server.

Server Affinity Strategies

Bloomreach Experience Manager supports two different load balancer server affinity strategies:

Source IP affinity

With this strategy the load balancer directs all client traffic from a specific source IP to the same backend server. This is a robust solution but has the disadvantage that the traffic can be unevenly distributed when a large group of users are accessing the CMS from behind a shared NAT. For example from within a corporate network all users then might end up being served by a single backend server.

This strategy is incompatible with headless integration scenarios using an external SPA frontend application, since all requests to the Delivery API will originate at the IP of the frontend application.

Injecting a dedicated server affinity cookie

With this strategy the load balancer injects a dedicated cookie which keeps track of the server affinity. It is important to use a separate cookie and not (re)use the session cookies set by the application.

This is the recommended strategy in all implementation scenarios.

This strategy is required in headless integration scenarios in combination with additional requirements for the frontend application.

As an illustration how to configure this, the following HAProxy backend configuration fragment will inject a SERVERID cookie to track the server affinity:

backend brxm 
  balance roundrobin
  cookie SERVERID insert nocache httponly maxidle 1h
  server node1 10.10.10.1:8080 check cookie node1
  server node2 10.10.10.2:8080 check cookie node2

Cookie Path

The Path of the SERVERID cookie must be on / . After logging in into the CMS there should be a cookie like the following:

If the Path is for example /cms, the Experience manager app won't work, most likely showing a 409 status code for some requests. See Channel Manager Troubleshooting.

Additional Requirements for Frontend Applications in Headless Integrations

The Delivery API provides access to preview data using JSON Web Token-based authentication. When Bloomreach Experience Manager is running behind a load balancer, server affinity is required to access the preview data. That requirement is applicable only to the preview integration and must not be used in live mode.

In addition to the SERVERID cookie (see above), in headless integration scenarios it is also required to pass a Server-Id header in the outgoing Delivery API request. When Bloomreach Experience Manager is running behind a load balancer, the value for the Server-Id header will be passed in the server-id query string parameter. The parameter will be appended next to the token parameter to the preview URL configured for a channel in the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url parameter.

The SPA SDK supports the server-id query parameter handling and the integration should work out of the box without extra configuration.

The load balancer must be configured to take both the SERVERID cookie and the Server-Id header into account. Below is an example HAProxy backend configuration:

backend brxm 
  balance roundrobin
  cookie SERVERID insert nocache httponly maxidle 1h
  use-server node1 if { req.hdr(Server-Id) -i node1 }
  server node1 10.10.10.1:8080 check cookie node1
    use-server node2 if { req.hdr(Server-Id) -i node2 }
  server node2 10.10.10.2:8080 check cookie node2