(Optional) Load balancing through TCP/IP port sharing

You need the assistance of a TCP/IP administrator to complete this customization task, which requires the following resources or special customization tasks:

Update TCP/IP profile to define port sharing.

RSE API supports running multiple servers on a single system, which share a single TCP/IP port for communication with clients. Therefore, you can spread the workload across multiple address spaces and avoid a single point of failure at the server level.

Note: More elaborate high-availability setups, like Distributed Dynamic VIPA to avoid a single point of failure at the z/OS level, are also supported. The setup for RSE API is similar to the setup for prerequisite product IBM® Explorer for z/OS®. For more details, see the IBM Explorer for z/OS Host Configuration Reference Guide (SC27-8438).

RSEAPI started task updates

The RSEAPI started task JCL has the startup variable SRVNUM to differentiate server-specific resources, like log files and configuration details in a shared setup. This startup argument must be unique per server instance that is started as part of the shared port setup. Other startup arguments must be the same for all these servers.

rseapi.env updates

Ensure that the RSEAPI started tasks that use a shared port must use the same rseapi.env configuration file.

The following variables are related to port sharing. For more information, see rseapi.env, the RSE API configuration file.

RSEAPI_PORT_HTTP_x

All RSEAPI started tasks will look for their own server API port, where x matches the value of the SRVNUM startup argument. For port sharing, all RSEAPI started tasks must use the same API port. Use the following sample definitions to make the setting:

RSEAPI_PORT_HTTP_1=6800
RSEAPI_PORT_HTTP_2=${RSEAPI_PORT_HTTP_1}
RSEAPI_PORT_HTTP_3=${RSEAPI_PORT_HTTP_1}
…

RSEAPI_PORT_SHUTDOWN_x

All RSEAPI started tasks will look for their own server shutdown port, where x matches the value of the SRVNUM startup argument. To stop a specific server, the server shutdown ports must be unique for each server. Use the following sample definitions to make the setting:

RSEAPI_PORT_SHUTDOWN_1=60801
RSEAPI_PORT_SHUTDOWN_2=60802
RSEAPI_PORT_SHUTDOWN_3=60803
…

RSEAPI_SHARED_JWT_HMAC

When you use JSON Web Tokens (JWT) for client authentication in a shared-port setup, this variable must be set to true so that the involved RSE API servers can accept a JWT that is created by another server in the port sharing group.

TCP/IP updates

Shared ports are defined by the PORT statement in the TCP/IP profile. A shared port definition reserves a specific port number to be shared by specific z/OS address space job names. The following two options of the PORT statement control port sharing. For the description of the PORT statement, see the z/OS Communications Server: IP Configuration Reference (SC27-3651).

SHAREPORT: Requests are distributed by a weighted round-robin distribution method based on the Servers' accept Efficiency Fractions (SEFs) of the listeners that share the port.
SHAREPORTWLM: Requests are distributed based on z/OS Workload Manager (WLM) server-specific recommendations, which are modified by the SEF values for each listener. Load balancing can be more efficient if you consider the status that is provided by dynamic feedback from WLM.