API Gateway configuration parameters
As an application developer who wants to change the default configuration of the API Mediation Layer, set the following parameters by modifying the
<Zowe install directory>/components/gateway/bin/start.sh file:
- Runtime configuration
- Service configuration
- Zuul configuration
- Hystrix configuration
This section describes runtime configuration properties.
This property is used to set the API Gateway hostname.
This property is used to set the API Gateway port.
This property specifies the Discovery Service URL used by the service to register to Eureka.
Set the value of this property to
trueto advertize a service IP address instead of its hostname.
- If you set this property to
trueon the Discovery Service, ensure that you modify the value of
discoveryLocations:to use the IP address instead of the hostname. Failure to modify the
discoveryLocations:value prevents Eureka from detecting registered services. As a result, the available-replicas is empty.
- Enabling this property may also cause issues with SSL certificates and Subject Alternative Name (SAN).
- If you set this property to
This property specifies the location of the EhCache used by Spring.
Note: It is necessary for the API ML process to have write access to the cache location.
This parameter makes it possible to prevent server certificate validation.
Important! Ensure that this parameter is set to
truein production environments. Setting this parameter to
falsein production environments significantly degrades the overall security of the system.
This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is
This parameter lets you view the Zowe version by using the
/versionendpoint. To view the version requires setting up the launch parameter of the API Gateway -
apiml.zoweManifestwith a path to the Zowe build
manifest.jsonfile. This file is usually located in the root folder of Zowe build. If the encoding of
manifest.jsonfile is different from UTF-8 and IBM1047, ensure that you set up the launch parameter of API Gateway -
apiml.zoweManifestEncodingwith correct encoding.
Note: It is also possible to know the version of API ML and Zowe (if API ML used as part of Zowe), using the
/gateway/api/v1/versionendpoint in the API Gateway service in the following format:
This property is relevant only when the JWT is generated by the API Mediation Layer. API ML generation of the JWT occurs in the following cases:
z/OSMF is only available as an older version which does not support JWT tokens
The SAF provider is used
To use a custom configuration for z/OSMF which changes the expiration of the LTPA token, it is necessary to also set the expiration in this parameter.
Note: The default value is 8 hours which mimicks the 8 hour default expiration of the LTPA token in z/OSMF.
Follow these steps:
- Open the file
<Zowe install directory>/components/gateway/bin/start.sh.
- Find the line that contains
- Before this line, add a new line in the following format:where:
refers to the specific time before expiration
- Restart Zowe&trade.
In a multiple network stack environment (CINET), when one of the stacks fails, no notification or Java™ exception occurs for a Java program that is listening on an
INADDR_ANYsocket. When new stacks become available, the Java application does not become aware of these stacks until the application rebinds the
INADDRsocket. By default, this parameter is enabled in the API Gateway. As a result, the
NetworkRecycledExceptionexception is thrown to the application to allow it to either fail or attempt to rebind. For more information, see the IBM documentation.
This property is a standard Java system property which is used by the disk-based storage policies. This property determines where the JVM writes temporary files, including those written by these storage policies. The default value is typically
/tmpon Unix-like platforms.
This property can be used to unconditionally add active profiles. For more information, see the Spring documentation.
server.maxTotalConnections and server.maxConnectionsPerRoute
These two properties are used to set the number of concurrent connections. Further connection requests that put the number of connections over either of these limits are queued until an existing connection completes. The API Gateway is built on top of Apache HTTP components that require these two connection limits for concurrent requests.
You can add additional environment variables to store configuration properties for the API Mediation Layer.
Note: Use either dot separation, or the UPPER_CASE naming convention when adding an additional environmental variable.
One use case for adding an environmental variable is to change the authentication provider. The
SAF Authentication Provider allows the API Gateway to authenticate directly with the z/OS SAF provider that is installed on the system. The user needs a SAF account to authenticate. Use this procedure to customize authentication provider.
Follow the steps:
Open the file
<Zowe instance directory>/zowe.yaml.
Add a new line to the environments section with the following property:
For information about service configuration parameters, see Onboarding a REST API service with the Plain Java Enabler (PJE).
As a provider for routing and filtering, the API Gateway contains a Zuul configuration as shown in the following example.
decodeUrl: false # Flag to indicate whether to decode the matched URL or use it as is
The Zuul configuration allows the API Gateway to act as a reverse proxy server through which API requests can be routed from clients on the northbound edge to z/OS servers on the southbound edge.
Note: For more information about Zuul configuration parameters, see the Spring Cloud Netflix documentation.
The API Gateway contains a Hystrix configuration as shown in the following example.
Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems, services and third-party libraries, stop cascading failure, and enable resilience in complex distributed systems where failure is inevitable.
Note: For more information about Hystrix configuration parameters, see the Netflix - Hystrix documentation.
The communication server on z/OS provides a functionality to encrypt HTTP communication for on-platform running jobs. This functionality is refered to as Application Transparent Transport Layer Security (AT-TLS). Starting with Zowe version 1.24, it is possible to leverage AT-TLS within the API Mediation Layer. Each API ML component can run with AT-TLS rules applied. Some components, such as the Discovery service, can be made AT-TLS aware by enabling the AT-TLS profile, whereby TLS information can be utilized. Such information could be a client certificate. To enable the AT-TLS profile and disable the TLS application in API ML, update
zowe.yaml with following values under the respective component in the
While API ML can not handle TLS on its own, the Mediation Layer needs information about the server certificate that is defined in the AT-TLS rule. Update the
zowe.yaml file for each respective APIML component in the
components sections with the path to the SAF Key ring from the AT-TLS rule and specify the alias that is used for Inbound communication:
Note: This procedure does not configure AT-TLS on z/OS, but rather enables API ML to work with AT-TLS in place.