Skip to content

Load Balancer

Put a load balancer in front of the MetaMiner Server (MMS) on each high-availability node, so users and scripts reach the Flow Scheduler at one address and a failed node is taken out of rotation.

The balancer serves the Flow Scheduler web interface and its API on MMS. Every node can serve users; only the leader runs flows, and leadership plays no part in routing.

Before you begin

  • The cluster is set up and every node is healthy. See Set Up High Availability.
  • Your load balancer supports HTTP health checks and a balancer-generated affinity cookie.
  • The load balancer has a public address and a TLS certificate for it. It terminates TLS for clients.

Steps

  1. Add each node's MMS listener as a back end, with that node's own scheme and port (49714 by default).

  2. Configure the health check on each back end:

    Setting Value
    Path GET /api/flowscheduler/ready
    Healthy answer HTTP 200 only (not any 2xx or 3xx). Do not match on the response body.
    Interval 5 seconds
    Mark down after 2 failed checks (about 10 seconds)
    Mark up after 1 to 2 good checks

    The ready check answers 200 only when the node has finished starting, its database connection is fresh, its scheduler is running and it can reach its MMS. It answers 503 otherwise, including when the node's Flow Scheduler is down. It returns to 200 only after the node has been healthy for about 10 seconds. A standby is a healthy back end.

    Do not health-check /flowscheduler/ or /health

    MMS serves /flowscheduler/ itself, so it answers 200 even when the node's Flow Scheduler is down. /api/flowscheduler/health is a liveness check only. Use /api/flowscheduler/ready.

  3. Turn on session affinity with a cookie generated by the balancer:

    Cookie attribute Value
    Name Any, for example fss_lb_affinity
    Path /
    Secure On
    HttpOnly On
    SameSite None, so the SAML sign-in post from the identity provider keeps the pin

    Let the health check override a stale affinity cookie, so users move to a healthy node when theirs fails. Do not use source-IP affinity: network address translation can put many users behind one address.

  4. Route to all healthy nodes. Do not send web traffic to the leader only (for example with /api/flowscheduler/leader-health): every handover would then sign all users out.

  5. On every node, in MMA Tools > FSS Configuration..., Properties tab, set notifications.fss.external.url to the load balancer's public address, for example https://<lb-host>, so links in e-mail open through the balancer. This setting is per node: set it on each node and restart its Flow Scheduler.

  6. If users sign in with SAML, use the balancer's public address as the service provider identity on every node, so the identity provider posts back through the balancer:

    1. On each node, on the SAML / SSO tab, set SP Entity ID: to https://<lb-host>/flowscheduler and ACS / Return URL: to https://<lb-host>/api/flowscheduler/saml/acs, then click Save SAML configuration. The change applies without a restart.
    2. Copy the whole server\config\saml\ folder, including the IdP metadata file, to every node, so all nodes have identical settings.
    3. In the identity provider, register the service provider with the same entity ID and ACS URL, or import its metadata from https://<lb-host>/api/flowscheduler/saml/metadata.

    The short-lived sign-in state after SSO is kept in the shared database, so the identity provider's post and the next request can land on different nodes.

  7. Give REST API callers the balancer address as the base URL: https://<lb-host>. See REST API.

API calls through the balancer

An API write that reaches a standby is refused with 409 NOT_LEADER and names the leader. See Status Codes and Errors. Backups are per node, so call each node's own address for the Flow Scheduler Backup API.

Verify

Check Expected
GET https://<lb-host>/api/flowscheduler/ready 200 while the nodes are healthy
Stop the Flow Scheduler on one node The balancer marks that back end down within about 10 seconds and sends traffic to the other node
Repeat requests with the affinity cookie They stay on one node
Run on a task while pinned to a standby Accepted; the leader runs it
SSO sign-in through the balancer Lands in the web interface; the identity provider posts back to the balancer address
https://<lb-host>/api/flowscheduler/saml/metadata Shows the balancer address as entity ID and ACS URL

Troubleshooting

Users are signed out or see session-expired errors

Session affinity is missing or not applied to every path. Sessions live in one node's memory, so a request that reaches the other node is not signed in. Use a balancer cookie with Path=/.

Sign in with SSO appears and disappears

The nodes have different SAML settings. Copy the same server\config\saml\ folder to every node.

The identity provider rejects the sign-in request

The entity ID or ACS URL registered in the identity provider does not match the SAML / SSO tab. Use the balancer address in both places.

A node with a stopped Flow Scheduler still gets traffic

The health check uses /flowscheduler/ or /api/flowscheduler/health. Switch it to /api/flowscheduler/ready and accept 200 only.

Next steps