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/api-mediation/bin/start.sh file:

• Runtime configuration
• Service configuration
• Zuul configuration
• Hystrix configuration

Runtime configuration

This section describes other configuration properties you might see in the file.

• apiml.service.hostname

  This property is used to set the API Gateway hostname.

• apiml.service.port

  This property is used to set the API Gateway port.

• apiml.service.discoveryServiceUrls

  This property specifies the Discovery Service URL used by the service to register to Eureka.

• apiml.service.preferIpAddress

  Set the value of this property to true to advertize a service IP address instead of its hostname.

  Notes:

  • If you set this property to true on the Discovery service, ensure that you modify the value of discoveryLocations: to use the IP address instead of the hostname. Failure to modify the value prevents Eureka from detecting registered services, and as a consequence the available-replicas will be empty.
  • Enabling this property may also cause issues with SSL certificates and Subject Alternative Name (SAN).

• apiml.cache.storage.location

  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.

• apiml.security.ssl.verifySslCertificatesOfServices

  This parameter makes it possible to prevent server certificate validation.

  Important! Ensure that this parameter is set to true in production environments. Setting this parameter to false in production environments significantly degrades the overall security of the system.

• apiml.security.auth.zosmfServiceId

  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 zosmf.

• apiml.zoweManifest

  This parameter lets you view the Zowe version by using the /version endpoint. To view the version requires setting up the launch parameter of the API Gateway - apiml.zoweManifest with a path to the Zowe build manifest.json file. This file is usually located in the root folder of Zowe build. If the encoding of manifest.json file is different from UTF-8 and IBM1047, it requires setting up the launch parameter of API Gateway - apiml.zoweManifestEncoding with 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 /api/v1/gateway/version endpoint in the API Gateway service in the following format:

https://localhost:10010/api/v1/gateway/version    

• apiml.security.auth.tokenProperties.expirationInSeconds

  This property is relevant only when the JWT token is generated by the API Mediation Layer. API ML generation of the JWT token 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 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:

  1. Open the file <Zowe install directory>/components/api-mediation/bin/start.sh.
  2. Find the line that contains the -cp ${ROOT_DIR}"/components/api-mediation/gateway-service.jar":/usr/include/java_classes/IRRRacf.jar.
  3. Before this line, add a new line in the following format:

     -Dapiml.security.auth.tokenProperties.expirationInSeconds={expirationTimeInSeconds} \

     where:
  • {expirationTimeInSeconds} refers to the specific time before expiration
  4. Restart Zowe&trade.

• ibm.serversocket.recover

  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_ANY socket. Also, when new stacks become available, the Java application does not become aware of them until it rebinds the INADDR socket. By default, this parameter is enabled in the API Gateway, meaning that an exception (NetworkRecycledException) is thrown to the application to allow it either to fail or to attempt to rebind. For more information, see the IBM documentation.

• java.io.tmpdir

  This property is a standard Java system property which is used by the disk-based storage policies. It determines where the JVM writes temporary files, including those written by these storage policies. The default value is typically /tmp on Unix-like platforms.

• spring.profiles.include

  This property can be used to unconditionally add active profiles. For more information, see Spring documentation.

Service configuration

For more information about service configuration parameters, see Onboarding a REST API service with the Plain Java Enabler (PJE).

Zuul configuration

As a provider for routing and filtering, the API Gateway contains a Zuul configuration as shown in the following example:

zuul:    sslHostnameValidationEnabled: false    addProxyHeaders: true    traceRequestBody: true    ignoreSecurityHeaders: false    includeDebugHeader: false    sensitiveHeaders: Expires,Date    ignoredPatterns:        - /ws/**    host:        connectTimeoutMillis: ${apiml.gateway.timeoutMillis}        socketTimeoutMillis: ${apiml.gateway.timeoutMillis}    forceOriginalQueryStringEncoding: true    retryable: true    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 its northbound edge to z/OS servers on its southbound edge.

Note: For more information about Zuul configuration parameters, see the Spring Cloud Netflix documentation.

Hystrix configuration

The API Gateway contains a Hystrix configuration as shown in the following example:

hystrix:    command:        default:            fallback:                enabled: false            circuitBreaker:                enabled: false            execution:                timeout:                    enabled: false                isolation:                    thread:                        timeoutInMilliseconds: ${apiml.gateway.timeoutMillis}                    strategy: SEMAPHORE                    semaphore:                        maxConcurrentRequests: 100000

Hystrix is a latency and fault tolerance library designed to isolate points of access to remote systems, services and 3rd 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.