> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/rpm/rpm-ha/load-balancer.md).

# Configure the load balancer

What to put in front of the three hosts, how to health-check them, and the session behaviour to configure.

Users reach a three-node cluster through a load balancer, which distributes requests across the three hosts and takes a failed one out of rotation. OpenIAM does not supply the load balancer — use whatever your organisation already runs.

## What this covers, and how long it takes

<table><thead><tr><th width="146"></th><th></th></tr></thead><tbody><tr><td><strong>You get</strong></td><td>User traffic distributed across the three hosts, with failed nodes removed automatically</td></tr><tr><td><strong>Time</strong></td><td>30 minutes, plus your organisation's change process</td></tr><tr><td><strong>Hosts</strong></td><td>Your load balancer, and the three cluster hosts</td></tr><tr><td><strong>Downtime</strong></td><td>None</td></tr><tr><td><strong>Reversible</strong></td><td>Yes</td></tr></tbody></table>

## Where this page sits in the sequence

Come here after [*Start and verify*](/installation/rpm/rpm-ha/start-and-verify.md) steps 1 to 5 pass on all three hosts. After this page, enable HTTPS and complete first sign-in through the load balancer's name, then return to *Start and verify* for step 6 and the node-loss test.

## Before you start

* The three hosts installed, and [*Start and verify*](/installation/rpm/rpm-ha/start-and-verify.md) steps 1 to 5 passing on each.
* A DNS name for the platform, pointing at the load balancer. This is the address users type, and the address that goes on the content provider.

## Set these first

{% code overflow="wrap" %}

```bash
export NODE1=<first node>
export NODE2=<second node>
export NODE3=<third node>
export NODES="$NODE1 $NODE2 $NODE3"
export OPENIAM_URL=<the load balancer's DNS name>
```

{% endcode %}

***

## Configure it

### 1. Define the pool

<table><thead><tr><th width="182">Setting</th><th>Value</th></tr></thead><tbody><tr><td><strong>Members</strong></td><td>All three hosts</td></tr><tr><td><strong>Port</strong></td><td>80, or 443 once you enable HTTPS</td></tr><tr><td><strong>Algorithm</strong></td><td>Round robin is a good default. Least-connections also works well</td></tr></tbody></table>

### 2. Health check each member

Use the identity provider's sign-in path — it exercises the reverse proxy and a real application behind it, rather than only confirming that a port is open:

<table><thead><tr><th width="252.39999389648438">Setting</th><th>Value</th></tr></thead><tbody><tr><td><strong>Type</strong></td><td>HTTP <code>GET</code></td></tr><tr><td><strong>Path</strong></td><td><code>/idp/login</code></td></tr><tr><td><strong>Port</strong></td><td>80</td></tr><tr><td><strong>Expected</strong></td><td><code>200</code></td></tr><tr><td><strong>Interval</strong></td><td>30 seconds</td></tr><tr><td><strong>Timeout</strong></td><td>5 seconds</td></tr><tr><td><strong>Unhealthy after</strong></td><td>2 consecutive failures</td></tr><tr><td><strong>Healthy after</strong></td><td>5 consecutive successes</td></tr></tbody></table>

A simple TCP check on port 80 will keep a node in rotation when its proxy is running and the platform behind it is not. The HTTP check is the one worth configuring.

**The thresholds are deliberately asymmetric.** A failing node leaves rotation quickly — two checks — and a recovered one returns slowly, five checks at 30-second intervals, so it does not take traffic until it is genuinely serving. That is about 150 seconds back into rotation. Shorten the interval if you need faster recovery; keep the threshold.

### 3. Set session behaviour

OpenIAM holds session state in its shared cache, so any node can serve any request. Session affinity is therefore **not required**, and leaving it off is the simplest configuration.

Enabling it anyway — source-address or cookie-based — is harmless and slightly reduces cache traffic. Do not enable it in a form that pins a client to a member that has failed its health check.

### 4. Preserve the client address and protocol

The platform builds links and evaluates policy from the request, so it needs to see the original address and scheme rather than the load balancer's:

{% code overflow="wrap" %}

```
X-Forwarded-For    <client address>
X-Forwarded-Proto  http | https
X-Forwarded-Host   <the name users typed>
```

{% endcode %}

Most load balancers add these by default. Confirm yours does.

### 5. Terminate TLS

Two supported arrangements:

* **At the load balancer**, forwarding to the hosts on port 80. Usually simpler, and it keeps certificate renewal where your organisation already manages it. Set `X-Forwarded-Proto: https`.
* **On each host**, with the load balancer passing TLS through to port 443. See [*Enable HTTPS*](/installation/rpm/rpm-single-node/enable-https.md), applied to all three.

### 6. Set the content provider to the load balancer's name

**This step happens after this page.** Complete [*Enable HTTPS*](/installation/rpm/rpm-single-node/enable-https.md) and then [*First sign-in*](/installation/rpm/rpm-single-node/first-sign-in.md) through the load balancer's name, and set the content provider's **Domain Pattern** to that name there. Then return to [*Start and verify*](/installation/rpm/rpm-ha/start-and-verify.md) for step 6 and the node-loss test.

In the Webconsole, the content provider's **Domain Pattern** must be the name users type — the load balancer's DNS name, not any individual host's. Otherwise the platform builds links pointing at one node and the balancing is bypassed.

***

## Verify it

**Every member is healthy:**

{% code overflow="wrap" %}

```bash
for h in $NODES; do
  printf '%-20s %s\n' "$h" "$(curl -s -o /dev/null -w '%{http_code}' "http://$h/idp/login")"
done
```

{% endcode %}

**Expected: `200` from all three.**

**Traffic reaches all three.** Request through the load balancer several times and confirm the responses come from different hosts. Watch each host's proxy log:

{% code overflow="wrap" %}

```bash
tail -f /var/log/httpd/mod_openiam_access_log
```

{% endcode %}

**A node can be lost.** This is the test that matters:

{% code overflow="wrap" %}

```bash
# On one node
openiam-cli stop
```

{% endcode %}

Then confirm the load balancer marks it down within its threshold, that the console stays available through the load balancer, and that a user session established before the stop continues working. Start it again and confirm it returns to rotation.

**Record how long the failover took.** That number is what your availability commitment rests on.

## If it goes wrong

| What you see                                          | What it means                                                              | What to do                                                                                                                                     |
| ----------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| One member always unhealthy                           | The platform on that host is not serving                                   | Run [*Start and verify*](/installation/rpm/rpm-ha/start-and-verify.md) on it                                                                   |
| Users are signed out when a node fails                | Session state is not shared, or affinity is configured to prevent failover | Confirm the cache tier is clustered — [*The clustered tiers*](/installation/rpm/rpm-ha/form-the-clusters.md) — and review the affinity setting |
| Links point at an individual host                     | The content provider carries a host name rather than the load balancer's   | Step 6                                                                                                                                         |
| Sign-in loops after enabling TLS at the load balancer | The platform believes the request arrived over HTTP                        | Confirm `X-Forwarded-Proto` is set, and that the content provider has SSL enabled                                                              |

## What this procedure does not cover

Choosing or building the load balancer, its own availability, and its certificate management. Those are yours, and the requirements here — health check, session behaviour, timeouts and the two ports — apply to whichever product you use. TLS on the hosts themselves is [*Enable HTTPS*](/installation/rpm/rpm-single-node/enable-https.md).

## Related

* [*The clustered tiers*](/installation/rpm/rpm-ha/form-the-clusters.md)
* [*Start and verify*](/installation/rpm/rpm-ha/start-and-verify.md)
* [*Enable HTTPS*](/installation/rpm/rpm-single-node/enable-https.md)
* [*Ports*](/installation/rpm/rpm-ha/ports.md)

*Applies to OpenIAM 2026.8.1.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/rpm/rpm-ha/load-balancer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.