> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs.itential.com/itential-platform/6/llms.txt
> - 2023.2: https://docs.itential.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure a load balancer

> Configure a load balancer in front of a clustered Itential Platform deployment, including HTTPS, health checks, and examples for HAProxy, Nginx, and F5.

Place a load balancer in front of your clustered Itential Platform deployment to distribute client and API traffic across nodes and route around unhealthy ones. Use these practices in any high availability deployment where multiple Platform nodes share the same MongoDB and Redis backends. You'll configure HTTPS between the load balancer and nodes, set up health checks, and use example configurations for HAProxy, Nginx, and F5.

## Topology

![Clients connect to a load balancer virtual IP address on port 443. The load balancer forwards requests over HTTPS on port 3443 to Platform nodes that share the same MongoDB and Redis backends.](/_fern-files/_img/27795b2604c61d16e70daaef991d35b3dbad69f31bd934c67ad394e8e9892579.webp)

Connect client and API traffic through the load balancer's virtual IP address, or VIP, on port 443, not directly to a node. The load balancer terminates TLS on the VIP and re-encrypts traffic to each node over HTTPS on port 3443. For details, see [HTTPS between the load balancer and nodes](#https-between-the-load-balancer-and-nodes).

You can add nodes to the load balancer pool as your capacity needs grow. These nodes are `IP1` through `IPX` in the diagram. Connect all nodes to the same MongoDB and Redis instances. The load balancer can send any request to any node, so every node must see the same session and cluster state.

### Restart apps and adapters

Connect directly to each node when you restart an app or adapter. Platform can't restart an app or adapter across all nodes in a cluster at once. If you restart through the VIP, the restart applies only to the node that handles the request. To restart an app or adapter cluster-wide, restart it on each node individually.

For information on how to restart apps and adapters, see [Status](/itential-platform/admin-essentials/status).

## HTTPS between the load balancer and nodes

Enable TLS with valid certificates on each Platform node. The connection between the load balancer and each node must use HTTPS on port 3443, regardless of authentication method. This includes OAuth through Okta, Azure, or PingID, and LDAP.

Don't use plain HTTP between the load balancer and nodes. Plain HTTP causes issues with OAuth and Gateway Manager. These issues occur for the following reasons:

* **Secure session cookies**: Platform sets the `Secure` attribute on the `connect.sid` session cookie, so browsers send the cookie only over HTTPS. If the load balancer downgrades the connection to HTTP, session handling and the OAuth redirect and callback flow can fail, sometimes without an error message.
* **Protocol-sensitive OAuth flows**: OAuth token exchanges and redirect URIs depend on using HTTPS. Plain HTTP between the load balancer and nodes can expose tokens and cookies and cause callback URL mismatches.

Itential recommends the following load balancer settings:

* Re-encrypt traffic, also called TLS bridging, instead of terminating TLS and forwarding plain HTTP.
* Use certificates from a trusted certificate authority, or from a private certificate authority that the load balancer trusts.
* Enable certificate verification.

Work with your network team to apply your organization's certificate and security standards.

> **Note**
>
> Your OAuth provider or integration might have additional callback URL or cookie domain requirements. Confirm these requirements with Itential for your environment.

## Health checks

### Endpoint

Send a `GET` request to `/health/status` over HTTPS on port 3443 of each node. The endpoint doesn't require authentication. It returns a `200` response with a JSON body like the following:

```json
{
  "host": "host01",
  "serverId": "host01",
  "timestamp": 1787760248275,
  "apps": "running",
  "adapters": "running",
  "services": [
    {"service": "redis", "status": "running"},
    {"service": "mongo", "status": "running"},
    {"service": "vault", "status": "running"}
  ]
}
```

> **Warning**
>
> The endpoint returns a `200` response even when apps or adapters report `degraded`. A check for `200` confirms only that the node process is running and responding. It doesn't confirm that the node is fully healthy.

You can run one of two levels of health check:

* **Basic check**: Send `GET /health/status` and pass on any `2xx` response. This simple check confirms that the node responds successfully. It evaluates only the HTTP response status, so it works on every load balancer, including open source Nginx.
* **Deep check**: Send the same request, then inspect the response body. Fail the check if the body contains `degraded` or a service status other than `running`. Only load balancers that can match response content support this check, including HAProxy, F5, and Nginx Plus.

### Skip dependency checks

Add the query string `?exclude-services=true` to the health check URL, for example `/health/status?exclude-services=true`. This parameter skips the dependency checks for Redis, MongoDB, and Vault and returns only node-level status. Load balancers send health checks frequently, every few seconds per node, so skipping the dependency checks avoids unnecessary load on those services.

The response omits the `services` array:

```json
{
  "host": "host01",
  "serverId": "host01",
  "timestamp": 1787774875325,
  "apps": "running",
  "adapters": "running"
}
```

### Tune health check settings

Start with the following values, then adjust them to meet your service-level agreements.

| Parameter                  | Suggested value        |
| -------------------------- | ---------------------- |
| Check interval             | 5 to 10 seconds        |
| Timeout                    | 2 to 5 seconds         |
| Healthy threshold (rise)   | 2 consecutive passes   |
| Unhealthy threshold (fall) | 3 consecutive failures |

## Load balancer configuration examples

> **Note**
>
> The following HAProxy, Nginx, and F5 examples are for reference only. Directive names, syntax, and available options vary by product version. Before you use an example in production, verify it against the vendor documentation for your version of each product.

### HAProxy

The following example targets HAProxy 2.x. Directive availability and flags can differ between versions. Validate the example against the output of `haproxy -vv` and the HAProxy documentation for your installed version.

The example uses `mode http` because HAProxy needs Layer 7 features for `option httpchk` with a specific path and `http-check expect string` for the deep check. The `ssl` and `ssl verify` options on the `server` lines re-encrypt traffic to each node independently of `mode http`.

```config
backend itential_platform
    mode http
    balance roundrobin
    option httpchk GET /health/status?exclude-services=true
    http-check expect status 200
    # Deep check alternative (uncomment to require a body match instead of only a 200 response):
    # http-check expect string "\"apps\":\"running\""
    server ip1 <ip1>:3443 check ssl verify required ca-file /etc/haproxy/ca.pem inter 5s rise 2 fall 3
    server ip2 <ip2>:3443 check ssl verify required ca-file /etc/haproxy/ca.pem inter 5s rise 2 fall 3
    server ipX <ipX>:3443 check ssl verify required ca-file /etc/haproxy/ca.pem inter 5s rise 2 fall 3
frontend itential_platform_vip
    bind *:443 ssl crt /etc/haproxy/vip.pem
    default_backend itential_platform
```

### Nginx

The following examples target Nginx 1.2x and Nginx Plus R2x. Directive names and availability, especially `health_check match`, have changed across releases. Validate the examples against the output of `nginx -v` and the Nginx documentation for your installed version.

Open source Nginx doesn't support active health check probing. It supports only passive checks based on failed live requests, using `max_fails` and `fail_timeout`. Active health checks that match content, using `health_check match`, require Nginx Plus.

#### Open source Nginx with passive checks

```config
upstream itential_platform {
    zone itential_platform 64k;
    server ip1:3443 max_fails=3 fail_timeout=30s;
    server ip2:3443 max_fails=3 fail_timeout=30s;
    server ipX:3443 max_fails=3 fail_timeout=30s;
}
server {
    listen 443 ssl;
    ssl_certificate     /etc/nginx/vip.pem;
    ssl_certificate_key /etc/nginx/vip.key;
    location / {
        proxy_pass https://itential_platform;
        proxy_ssl_verify on;
        proxy_ssl_trusted_certificate /etc/nginx/ca.pem;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}
```

#### Nginx Plus with active deep checks

```config
upstream itential_platform {
    zone itential_platform 64k;
    server ip1:3443;
    server ip2:3443;
    server ipX:3443;
}
server {
    listen 443 ssl;
    location / {
        proxy_pass https://itential_platform;
        proxy_ssl_verify on;
        proxy_ssl_trusted_certificate /etc/nginx/ca.pem;
        health_check uri=/health/status?exclude-services=true interval=5s fails=3 passes=2 match=itential_healthy;
    }
}
match itential_healthy {
    status 200;
    body !~ "degraded";
}
```

### F5 BIG-IP Local Traffic Manager

The following example targets BIG-IP Local Traffic Manager 16.x and 17.x, configured with `tmsh`. Monitor and profile object syntax can differ between versions. Validate the example against the F5 BIG-IP documentation and the output of `tmsh help` for your installed version.

Use an HTTPS extended application verification monitor so that the monitor can inspect the response body, not only the status line:

```config
ltm monitor https itential_platform_monitor {
    defaults-from https
    destination *:3443
    interval 5
    timeout 16
    send "GET /health/status?exclude-services=true HTTP/1.1\r\nHost: p6.example.com\r\nConnection: Close\r\n\r\n"
    recv "\"apps\":\"running\""
    ssl-profile serverside-verify
}
ltm pool itential_platform_pool {
    monitor itential_platform_monitor
    members {
        ip1:3443 { }
        ip2:3443 { }
        ipX:3443 { }
    }
}
ltm virtual itential_platform_vip {
    destination vip_address:443
    pool itential_platform_pool
    profiles { clientssl-vip { context clientside } serverssl-backend { context serverside } }
}
```

For a basic F5 monitor, change the `recv` value to `200 OK`. Alternatively, use the built-in `https` monitor type against `/health/status` without a body match.

## Session affinity

Platform sets a `connect.sid` session cookie, but all nodes in the cluster store session and cluster state in the shared Redis and MongoDB instances. Any node can serve any request, so you don't need sticky sessions on the load balancer. Use round-robin or least-connections balancing.