Balancing Methods

Workbench | Enhanced Advanced

Balancing methods apply to Workbench Sessions only when they are run on the Workbench node itself. In that case, they define how the system distributes Workbench sessions amongst the Workbench nodes. If using the Job Launcher with Kubernetes or Slurm, the balancing method is used only for the rworkspaces program that supports the home page.

There are four methods available for balancing Workbench Sessions and rworkspaces across a cluster. The most appropriate method is installation specific and depends on the number of users and type of workloads they create.

Sessions

The default balancing method is sessions, which evenly distributes the number of sessions across the nodes of the cluster:

balancer = sessions

System load

The system-load balancing method distributes sessions based on the active workload of available nodes:

balancer = system-load

The metric used to establish active workload is the 5-minute load average, divided by the number of cores on the machine. This is a good choice if you expect widely disparate CPU workloads and want to ensure that machines with high CPU utilization don’t receive new sessions.

User hash

The user-hash balancing method attempts to distribute load evenly and consistently across nodes by hashing the username of clients:

balancer = user-hash

The hashing algorithm used is CityHash, which will produce a relatively even distribution of users to nodes. This is a good choice if you want the assignment of users/sessions to nodes to be stable.

Custom

The custom balancing method calls out to external script to make load balancing decisions:

balancer = custom

When custom is specified, Posit Workbench will execute the following script when it needs to make a choice about which node to start a new session on:

/usr/lib/rstudio-server/bin/rserver-balancer

This script will be passed two environment variables:

RSTUDIO_USERNAME — The user on behalf or which the new session is being created.

RSTUDIO_NODES — Comma separated list of the host and port of available nodes.

The script should return the node to start the new session on using its standard output. Note that the format of the returned node should be identical to its format as passed to the script (i.e. include the host and port).

Node host format

By default, the RSTUDIO_NODES list contains the hostnames as determined by the process described in Defining nodes for each node in the cluster. Alternatively, you can set the following option to configure RSTUDIO_NODES with list of raw IP addresses:

/etc/rstudio/rserver.conf

resolve-load-balancer-nodes=1

Note that this option is incompatible with SSL unless your servers’ SSL certificates contain IP addresses in their CN/SAN.