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
  • Environment variables
• Service configuration
• Zuul configuration
• Hystrix configuration
• AT-TLS

Runtime configuration

This section describes runtime configuration properties.

• 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 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).

• 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, ensure that you set 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 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:

  1. Open the file <Zowe install directory>/components/gateway/bin/start.sh.
  2. Find the line that contains -cp ${ROOT_DIR}"/components/gateway/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. When new stacks become available, the Java application does not become aware of these stacks until the application rebinds the INADDR socket. By default, this parameter is enabled in the API Gateway. As a result, the NetworkRecycledException exception is thrown to the application to allow it to either fail or 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. This property 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 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. For more information, see Apache documentation.

Environment variables

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:

1. Open the file <Zowe instance directory>/instance.env.

2. Add a new line with the following property:

   apiml.security.auth.provider=saf.

Service configuration

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

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}
        maxTotalConnections: ${server.maxConnectionsPerRoute}
        maxPerRouteConnections: ${server.maxTotalConnections}
    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 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.

Hystrix configuration

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

Example:

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

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.

AT-TLS

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 instance.env with the following environment variables:

SPRING_PROFILES_ACTIVE=attls
APIML_SSL_ENABLED=false 

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 instance.env file with the path to the SAF Key ring from the AT-TLS rule and specify the alias that is used for Inbound communication:

KEYSTORE=<SAF-key-ring-from-AT-TLS-rule>
KEYSTORE_TYPE=JCERACFKS
KEYSTORE_PASSWORD=<keyring-password>
KEY_ALIAS=<certificate-alias-from-AT-TLS-rule>

Note: This procedure does not configure AT-TLS on z/OS, but rather enables API ML to work with AT-TLS in place.