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.
- 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.
<httpEndpoint id="operationsHttpEndpoint" host="*" httpPort="<unique_http_port>" httpsPort="<unique_https_port>" />
- 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, anssl
element withid=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. - 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.
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.