You can run multiple Turnkey front-end nodes behind a load balancer and configure MDrivenServer hot standby nodes without allowing scheduled server-side work to run on more than one node.

Choose the correct load-balancing pattern

A load balancer presents one public address to users and routes requests to underlying nodes. Configure the pattern according to the component you are balancing.

Component	Supported pattern	Key requirement
Turnkey	Multiple active front-end nodes	Use sticky sessions so a user continues to reach the same node for the lifetime of that session.
MDrivenServer	Fail-over with one active node and hot standby nodes	Only the active node may run periodic server-side jobs.

For deployment and reverse-proxy guidance, see Documentation:Deployment and Documentation:Set up MDriven Turnkey on premise. For multi-server distribution of MDrivenServer data, see Documentation:Scaling MDrivenServer for multiple reasons.

Load balance Turnkey front-end nodes

Require sticky sessions

Configure session affinity (also called sticky sessions) in the load balancer. After the load balancer routes a user's session to one Turnkey node, it must continue to route that session to that node until the session ends or the node fails.

Without session affinity, successive requests can reach different nodes. This can create a new session and confuse the user.

Provide a health or availability endpoint

You can let a Turnkey application tell the load balancer whether a node should receive traffic. Create a health-check ViewModel page in your model and make it available through REST by setting RestAllow=true. Configure the load balancer to call that page on each Turnkey node and evaluate the agreed response.

For example, create a page named AreYouOkCheck. A load balancer can call:

https://APP/App#/AreYouOkCheck/$null$

Configure the health check to treat an HTTP 200 OK response as healthy, or agree on a response value such as Active or InActive and configure the load balancer to evaluate that value.

This endpoint is useful when you need to remove a node from normal traffic without removing the node itself. For example, return the response that the load balancer treats as inactive before you perform maintenance on one of five Turnkey nodes.

The health-check page must be reachable by the load balancer. Do not rely on a check that only works from a developer workstation or from inside a different network boundary.

Account for reverse-proxy URLs

MDrivenServer and Turnkey normally determine their own address from incoming requests. A load balancer health check can use an address that is not the address the application should use for itself. In that situation, configure HardServerUrl on each affected instance.

HardServerUrl.xml specifies the address that the individual instance should use and should avoid routing that instance back through the load balancer. When Turnkey is also involved, review the related MDrivenServer override setting described on HardServerUrl. Check the application log after startup to confirm that HardServerUrl.xml was found and applied.

Verify realtime traffic when applicable

If the application uses SignalR and Realtime, make sure the reverse proxy permits the SignalR negotiation, connection, start, ping, and reconnect requests. The .NET Framework SignalR version used in Turnkey is not compatible with cookie-based load balancing. Follow the verification URLs and guidance on SignalR and Realtime.

Configure MDrivenServer fail-over

Use fail-over rather than active load sharing for MDrivenServer periodic work. One MDrivenServer is the active, or hot, node. Other nodes are hot standbys. The load balancer decides which node is hot and must retain that decision while it is valid.

This rule is essential: do not allow hot standby nodes to execute server-side jobs. Periodic actions must run on one server only.

How the active-node check works

Each MDrivenServer exposes the following endpoint:

https://<yourserver>/home/ReturnNodeNameIfOk

The endpoint returns the name of the node that the load balancer considers active. Before MDrivenServer runs periodic actions, it compares that returned name with its own configured server name.

Endpoint result	Result for this MDrivenServer node
Returned node name exactly matches this node's configured server name	The node is hot and can run periodic actions.
Returned node name does not match this node's configured server name	The node is a standby and does not run periodic actions.
The node is hidden until a future time	The endpoint returns HTTP 500 until the configured time has passed. The load balancer interprets this as an error and keeps the node out of service.

Configure each MDrivenServer node

1. Open the UserAndRolesAdmin page in MDrivenServer.
2. Set the Server name for the node. The name must be unique within the load-balance group.
3. Set Load Balanced MDrivenServerUrl to the load-balanced address that exposes /home/ReturnNodeNameIfOk.
4. Enable Check Load balancer before running jobs on every node that must use the fail-over decision before running periodic actions.
5. Start the application and check LoadBalancerStatus. It records the last known result of the load-balancer check.
6. Configure the load balancer so that /home/ReturnNodeNameIfOk returns the unique name of the node selected as hot.
7. Verify that only the node whose name is returned runs periodic actions. Then test fail-over by changing the selected node and confirming that the previous node stops running those actions.

If Check Load balancer before running jobs is not enabled, MDrivenServer retains normal behavior: periodic actions run whenever the application is started. Do not use that behavior for a hot-standby configuration where more than one node can be started.

Temporarily remove a node from load balancing

Use HideFromLoadBalancerUntil to take a node out of service until a specified future DateTime. While that time is in the future, /home/ReturnNodeNameIfOk returns HTTP 500. Once the time has passed, the node becomes available again.

Use this when a node needs maintenance but should remain available for the access paths required to perform that work. Confirm that your load balancer treats HTTP 500 as an unhealthy result before relying on this mechanism.

Operational checklist

Before placing the configuration in production, verify all of the following:

• Turnkey load balancing uses sticky sessions.
• Every Turnkey health-check endpoint is reachable from the load balancer and returns the response the load balancer expects.
• Each MDrivenServer node has a unique server name.
• The load-balanced MDrivenServer URL reaches /home/ReturnNodeNameIfOk.
• Check Load balancer before running jobs is enabled on all participating MDrivenServer nodes.
• Only the selected hot MDrivenServer runs periodic actions.
• LoadBalancerStatus shows the expected latest check result.
• If a reverse proxy uses a different incoming address, HardServerUrl has been configured and verified in the startup log.
• If realtime features are in use, SignalR requests are permitted by the reverse proxy and the load-balancer method is compatible with the SignalR version.

See also

• Documentation:Deployment
• Documentation:HardServerUrl
• Documentation:SignalR and Realtime
• Documentation:Scaling MDrivenServer for multiple reasons
• Documentation:Server

Load balancing Turnkey and MDrivenServer

Turnkey and MDrivenServer use different load-balancing patterns.

Component	Pattern	Requirement
Turnkey	Use multiple nodes behind a load balancer.	Use sticky sessions so that a user returns to the same node during the session.
MDrivenServer	Use load-balancer fail-over.	Use only one MDrivenServer at a time; other nodes can be hot standbys. Hot standbys must not execute server-side jobs.

Turnkey availability checks

If the load balancer needs an application-specific availability signal, model a page and set RestAllow=true. Configure the page to return data agreed with the load balancer, for example Active or InActive, when application settings determine whether traffic should be sent to a node.

Give the page URL to the load balancer. For example, a page named AreYouOkCheck can be checked at:

https://APP/App#/AreYouOkCheck/$null$

The load balancer can check whether the URL returns HTTP 200.

MDrivenServer fail-over

To identify the MDrivenServer node currently selected by the load balancer:

1. Set a unique server name for every node in the load-balance group in the UserAndRolesAdmin page.
2. Give the load balancer the URL https://<yourserver>/home/ReturnNodeNameIfOk.
3. Set Load Balanced MDrivenServerUrl when periodic actions should check which node is currently selected by the load balancer.

Before running periodic actions, MDrivenServer checks the response from <LoadBalancedAdress>/home/ReturnNodeNameIfOk. If the returned value equals the name of the current server, that server is the selected node. If the names do not match, it is not the selected node and does not run periodic actions.

The latest load-balancer check result is written to LoadBalancerStatus.

If Check Load balancer before running jobs is not selected, periodic actions run normally whenever the application is started. Select it when periodic actions must run only on the selected MDrivenServer node.

Temporarily hide an MDrivenServer node

HideFromLoadBalancerUntil is a future DateTime value. While the value is in the future, the node-name endpoint returns HTTP 500 so that load balancers can interpret the node as unavailable. After the timestamp has passed, the node becomes online again.

This can be used to temporarily remove a node from load-balancer service before maintenance.

See also

• Documentation:Deployment

Load-balancing workflow

Use this workflow when you operate MDriven Turnkey or MDrivenServer on multiple nodes and need the load balancer to direct traffic and fail over safely.

Load balance Turnkey front ends

Configure sticky sessions for Turnkey. A sticky session keeps a user on the same node for the duration of that session.

For example, if a user starts a session on Turnkey node A, the load balancer must continue to send that session to node A until the session ends or node A fails. Do not distribute requests from the same active session between node A and node B.

You can also provide a health or maintenance signal to the load balancer:

1. Model a page that the load balancer can call.
2. Set the page to RestAllow=true.
3. Return the status value agreed with the load balancer, such as Active or InActive.
4. Configure the load balancer to call that page before it routes traffic to the node.

For example, an application can expose an AreYouOkCheck page. The load balancer can call https://APP/App#/AreYouOkCheck/$null$ and verify that the URL returns 200 OK. You can use the returned status to move traffic away from a node before maintenance.

Configure MDrivenServer fail-over

Use fail-over for MDrivenServer. Run only one MDrivenServer as the active, or hot, server at a time; other nodes can be hot standbys.

The load balancer must identify the active node and retain that choice. Give it the node-name endpoint:

https://<yourserver>/home/ReturnNodeNameIfOk

Set a unique server name for every node in the load-balance group in the MDrivenServer UserAndRolesAdmin page. For example, use Node1 for one node and Node2 for the standby. The load balancer checks the endpoint and uses the returned node name to identify the active node.

Ensure that only the hot server runs periodic actions

Periodic actions are server-side jobs. Hot standby nodes must not execute them, because the jobs must run on one server only.

1. In UserAndRolesAdmin, set a unique Server name for each node.
2. Set Load Balanced MDrivenServerUrl to the load-balanced address that exposes /home/ReturnNodeNameIfOk.
3. Select Check Load balancer before running jobs.
4. Verify that the load balancer returns the name of the node selected as the hot server.

Before MDrivenServer runs periodic actions, it checks the configured load-balanced URL. If the returned value equals the name of the current server, that server is the hot server and can run the jobs. If the names do not match, the server does not run periodic actions. The last result of this check is written to LoadBalancerStatus.

For example, if the server is named Node2 but the load balancer returns Node1, Node2 remains a standby and does not run periodic actions.

Take a node out of service

A node can request to be left out of load balancing by returning its node name followed by THIS NODE HAS REQUESTED TO BE LEFT ALONE from /home/ReturnNodeNameIfOk. Because the returned value no longer matches the node name, that node does not run periodic actions.

HideFromLoadBalancerUntil is a DateTime value used to hide a node until a future time. While that time is in the future, /home/ReturnNodeNameIfOk returns HTTP 500 so that the load balancer treats the node as unavailable. When the timestamp has passed, the node becomes online again.

Watch the load-balancing walkthrough for the configuration demonstration.