Configuring an HA environment for API calls from z/OS applications

You can configure a highly available IBM® z/OS® Connect environment that handles API calls from z/OS applications through API requesters.

Note: For more information about the concepts of high availability and the options you can choose, see High Availability.
The following diagram demonstrates the following topological characteristics:
  • Two IBM z/OS Connect servers run in each LPAR.
  • Sysplex Distributor provides high availability and workload balancing.
  • Port sharing is configured for each LPAR.
  • Sysplex Distributor is configured with the OPTLOCAL feature to take advantage of co-location optimization. For more information about configuring sysplex distributor to prefer local connections, see Sysplex distributor.
Figure 1. Topological characteristics of an HA configuration
Illustration of the HA environment for the API requesters scenario.

The following configuration steps demonstrate how to configure two servers in one LPAR for HA.

Prerequisites

  1. Create the first server, and configure the server properly to support API requesters, as described in Configuring IBM z/OS Connect to support API requesters.
  2. On the first server, go through the steps as outlined in the high-level workflow in What is the IBM z/OS Connect API requester? to configure, develop, deploy, and test all the required artifacts to call an API from your z/OS application. Ensure everything works properly on the first server.

General steps to configure for HA

The following steps demonstrate setting up HA with two IBM z/OS Connect servers in one LPAR, sharing a TCP/IP port.

  1. Set up HA for the first server:
    1. Set up TCP/IP port sharing.
      Note: Choose an unreserved port number. Use a different port number from the number that is used as the HTTP listener for incoming HTTP requests for services and APIs to access the backend z/OS assets.

      For more information about port sharing, see TCP/IP port sharing.

    2. Create a shared configuration file. This step involves moving the server.xml to a location that can be shared with the second server and creating another copy of the server.xml for the first server that points to the shared location.
      1. Stop the server.
      2. Create directories under /var/zosconnect to store the shared configuration file. For example, run the following command from the /var/zosconnect directory:
        mkdir -p shared/config
      3. Move the server.xml to a shared configuration directory with a new name. For example, rename it as haserver.xml.
      4. Create a server.xml for the server with the following content: 
        <?xml version="1.0" encoding="UTF-8"?>
<server description="z/OS Connect HA server1">
   <include location="${shared.config.dir}/haserver.xml"/>
</server>

        This configuration file includes the shared haserver.xml by using the Liberty property ${shared.config.dir} to reference the directory that contains the shared configuration files. This property points to the directory WLP_USER_DIR/shared/config. The include statement points to the renamed file, haserver.xml, in the shared location.

    3. Restart the server.
  2. Add a second server.
  3. Replace the default server.xml file on the second server with the server.xml file from the first server, so both the first server and the second server point to the shared location for the server configuration file.
  4. Start your second server.
The two server instances now share the same resources, and the HA environment for API requesters is configured.