Management of IBM z/OS Connect APIs, services, and API requesters in an HA environment

Considerations for querying, starting, stopping, deploying, updating, and undeploying APIs, services, and API requesters in an HA environment.

IBM® z/OS® Connect provides an administration interface for services, and a RESTful administration interface for APIs and API requesters. See Retrieving service information, Using the RESTful administration interface, and How to manage API requesters These administration interfaces connect to the HTTP or HTTPS port of a IBM z/OS Connect server and provide various functions such as:
  • Listing currently deployed APIs and services and retrieving details of an individual API or service.
  • Stopping and starting individual APIs or services.
  • Deploying, updating, or undeploying an API.

In an HA environment, HTTP, and HTTPS requests are targeted at a single host name and port but are then distributed across multiple servers when those servers use TCP/IP port sharing, Sysplex Distributor or both. Routing of an administration request cannot be guaranteed. Therefore, in an HA environment, administration, or operation actions through HTTP administration interfaces cannot be targeted at either a specific server or to all of the servers.

Querying APIs, services, and API requesters

If all the servers in a high availability group are configured with the same APIs, services, and API requesters, a shared HTTP or HTTPS port can still be used to retrieve details of currently deployed APIs, services, or API requesters, because any server can return the same information. However, it is not possible to determine the API and service status on any particular server. In that case, a second httpEndpoint can be configured as described below.

Starting and stopping APIs, services, and API requesters

To start or stop an individual API, service, or API requester, and to retrieve definitive deployment and status information from individual servers in an HA environment, configure a second httpEndpoint element in server.xml to specify an additional HTTP and HTTPS port pair for each server. These ports must be unique for each server and not shared. They are used only for the RESTful Administration interface administration and operation requests. Requests to invoke APIs and services continue to use the shared ports so that those requests are distributed across the servers.

For example, add the following entry into each server's server.xml file: 
<httpEndpoint id="operationsHttpEndpoint" host="*" httpPort="<unique_http_port>" httpsPort="<unique_https_port>" />
Note:
  1. In a production environment, you might restrict this administration endpoint to require SSL. By default, an httpEndpoint server configuration element uses the server's default SSL configuration, an ssl element with id=defaultSSLConfig. However, if you want to use different SSL certificates to protect requests over this administration endpoint, you can associate this endpoint with a different SSL configuration. For more information, see the Configuring an httpEndpoint to use an SSL configuration other than the default.
  2. Requests received on either httpEndpoint are authenticated against the same IBM z/OS Connect roles that are defined in your configured security repository. For more information, see Overview of IBM z/OS Connect security.

Deploying APIs

If the RESTful Administration interface is used to deploy, update, or undeploy APIs to a location directory that is shared by multiple servers, the time at which the change to the API takes effect in each server is unpredictable. This is because the server that the administration request is distributed to immediately implements the change to the API in its runtime and the API archive file is updated in the location directory. However, the other servers reflect the change to the API only when they refresh their API information, as specified by the updateTrigger attribute specified on zosconnect_zosConnectAPIs server configuration element. For more information, see zosconnect_zosConnectAPIs.

A better alternative in an HA environment is to deploy or update APIs by copying or FTPing the archive files in binary mode to a single location directory that is shared by all servers. Similarly, an API archive file can be deleted from the location directory so that new, updated, or deleted APIs are reflected on all servers at the same time. The change to the API archive file again takes effect in the running servers based on the updateTrigger attribute that is specified on zosconnect_zosConnectAPIs server configuration element.

When run in production, an mbean trigger is preferable to a polled trigger for performance reasons.

Deploying services

To deploy, update, or undeploy services in an HA environment, use the standard Liberty functions appropriate for your service provider.

Updates to the server configuration file can be made to the common shared configuration file and take effect dependent on the updateTrigger attribute that is specified on the config server configuration element. For more information, see Server configuration in the IBM WebSphere® Application Server for z/OS Liberty documentation.

If your IBM z/OS Connect services use DataXForms, creation, modification, or deletion of the data transformation files in the UNIX System Services directory can be updated based on the updateTrigger attribute that is specified on the zosconnect_zosConnectDataXform server configuration element. For more information, see zosconnect_zosConnectDataXform.

Note: If you specify the updateTrigger attribute value of mbean on any of the applicable server configuration elements, you must also configure your server to use the Java Management Extensions (JMX) connector, for more information see Using an MBean to trigger updates.