Configuring external access for application frontend or user interface (HTTP/HTTPS) endpoints

You can access the application user interface endpoints through the frontend service.

You must configure one of the below options:
  • Enable and configure ingress or routes (for OpenShift) on the applicable endpoints and setting the service type to ClusterIP. This is the recommended way and is enabled, by default.
  • Enable and configure frontend service by setting the service type to LoadBalancer or NodePort. In case of service type as LoadBalancer, an instance of the cloud provider, is configured and public IP is assigned for external access. In case of service type as NodePort, you can access the application using the node IP and node port configured by the service.
    Note: Using the NodePort service is not recommended, particularly for production environments.

With Kubernetes Ingress/OpenShift Route Configurations

  • ingress.enabled - Ingress can be enabled by setting this parameter as true. If ingress is enabled, asi.frontendService.type/ac.frontendService.type and api.frontendService.type are always set to ClusterIP.
  • asi.frontendService.type/ac.frontendService.type and api.frontendService.type Can be set to any valid Kubernetes service type supported by the platform – ClusterIP/LoadBalancer/NodePort/ExternalName. By default, it is set to ClusterIP.
  • asi.frontendService.extraPorts/ac.frontendService.extraPorts and api.frontendService.extraPorts - Additional ports can be configured for the frontend service as individual port mappings with the following port configuration options in values.yaml:
    • name: name for the port mapping.
    • port: service port number.
    • targetPort: target pod port name or number.
    • nodePort: service node port number. Applicable only for service type node port.
    • protocol: valid protocol for the container environment. Defaults to TCP.
  • asi.ingress.internal.host/ac.ingress.internal.host/api.ingress.internal.host - Fully qualified private or internal virtual domain names for asi/ac/api servers that resolves to the IP address of the cluster’s proxy node or router. Based on your network settings, it can be possible that multiple virtual domain names resolve to the same IP address of the proxy node or router. Any of those domain names can be used. For example, "example.com" or "test.example.com" or "apps.openshift4.example.com".
  • asi.ingress.internal.extraPaths/ac.ingress.internal.extraPaths - The additional internal context paths to be configured on the respective servers. Custom context paths can be configured on the asi or ac servers using HTTP Server Adapter. You can configure the below options for each extra path specified:
    • routePrefix: prefix to be added to the route name.
    • path: context path for the user web application.
    • servicePort: service port name or number for the application.
    • enableHttps: true or false based on whether TLS is enabled for the application.
  • asi.ingress.internal.tls.enabled/ac.ingress.internal.tls.enabled/api.ingress.internal.tls.enabled - Enable or disable TLS for internal routes. It is strongly recommended to enable TLS.
  • asi.ingress.external.host/ac.ingress.external.host/api.ingress.external.host - Fully qualified public or external virtual domain names for asi/ac/api servers that resolves to the IP address of the cluster’s proxy node or router. Based on your network settings, it can be possible that multiple virtual domain names resolve to the same IP address of the proxy node or router. Any of those domain names can be used. For example, "example.com" or "test.example.com" or "apps.openshift4.example.com".
  • asi.ingress.external.extraPaths/ac.ingress.external.extraPaths - The additional external or public context paths configured on the respective servers. Custom context paths can be configured on the asi or ac servers using HTTP Server Adapter. You can configure the below options for each extra path specified:
    • routePrefix: prefix to be added to the route name.
    • path: context path for the user web application.
    • servicePort: service port name or number for the application.
    • enableHttps: true or false based on whether TLS is enabled for the application.
  • asi.ingress.external.tls.enabled/ac.ingress.external.tls.enabled/api.ingress.external.tls.enabled - Enable or disable TLS for external routes. It is strongly recommended to enable TLS.
  • asi.externalAccess/api.externalAccess – Configure external access for the application from within client side tools like Graphic Process Modeler and other user interfaces. With ingress enabled, the externalAccess configurations is auto configured by the application with the ingress/route protocol, host names and ports along with the ingress TLS settings. The following configurations can be left as blank or with their default values in values.yaml:
    • asi/api.externalAccess.protocol
    • asi/api.externalAccess.address
    • asi/api.externalAccess.port
  • asi.internalAccess/api.internalAccess – Access the application endpoint with TLS configured on the respective application HTTPS port through ingress or route, which ensures end-to-end secure access to the application, particularly for OpenShift routes. The following configurations must be set:
    • asi/api.internalAccess.enableHttps: Enable this configuration to access the application on the HTTPS port.
    • asi.internalAccess.httpsPort: The default value is .Values.setupCfg.basePort + 1. In case the application war files are deployed on HTTP Server Adapter with TLS enabled on the ASI server, this can be set to the port configured for the adapter.
Note:

The installation of the application automatically creates default internal routes on:

  • Internal asi route host for these web contexts – /, /dashboard, /filegateway, /myfilegateway, /myfg, /ebicsClient, /mailbox, /queueWatch, /wsdl, /soap*
  • Internal api route host for these web contexts – /, /B2BAPIs, /propertyUI

The application installation automatically creates some default external routes on external asi route host for these web contexts – /myfilegateway, /myfg, /ebicsClient, /mailbox.

Any additional custom web context path can be configured using the extraPaths configurations available for both internal and external route hosts.

Configuring TLS for OpenShift Route

If TLS is enabled by setting asi.ingress.ssl.enabled/ac.ingress.ssl.enabled/api.ingress.ssl.enabled parameter to true, routes are created with the HTTPS URL. Also, the routes are exposed with the default certificate of the cluster.

For production environments, it is strongly recommended to obtain a CA certified TLS certificate and update the routes manually as shown below:
  1. Obtain a CA certified TLS certificate for the given asi.ingress.host/ac.ingress.host/api.ingress.host in the form of key and certificate files.
    The script below allows patching all the routes created through the Helm install with the certificate information based on the <Release_name>.
    
CRT_FN=<Path to Certificate>
KEY_FN=<Path to Private Key>
CABUNDLE_FN=<Path to CA Bundle File>

CERTIFICATE="$(awk '{printf "%s\\n", $0}' ${CRT_FN})"
KEY="$(awk '{printf "%s\\n", $0}' ${KEY_FN})"
CABUNDLE=$(awk '{printf "%s\\n", $0}' ${CABUNDLE_FN})

oc patch route $(oc get routes -l release=<Release_name> -o 
jsonpath="{.items[*].metadata.name}") -p 
'{"spec":{"tls":{"certificate":"'"${CERTIFICATE}"'", "key":"'"${KEY}"'" ,"caCertificate":"'"${CABUNDLE}"'"}}}'
  2. Specify the destination certificate for the application if internal access for the application is HTTPS enabled.
    
DEST_CABUNDLE_FN=<Path to Destination CA Bundle File>
DESTCABUNDLE=$(awk '{printf "%s\\n", $0}' ${ DEST_CABUNDLE_FN })

oc patch route $(oc get routes -l release=<Release_name> -o 
jsonpath="{.items[*].metadata.name}") -p 
'{"spec":{"tls":{"certificate":"'"${CERTIFICATE}"'", "key":"'"${KEY}"'" ,"caCertificate":"'"${CABUNDLE}"'", 
"destinationCACertificate":"'"${DESTCABUNDLE}"'"}}}'

Configuring TLS for Kubernetes Ingress

If TLS is enabled by setting asi.ingress.ssl.enabled/ac.ingress.ssl.enabled/api.ingress.ssl.enabled parameter to true, a secret is needed to hold the TLS certificate and the secret name must be configured for each of these parameters asi.ingress.ssl.secretname/ac.ingress.ssl.secretname/api.ingress.ssl.secretname.

For production environments, it is strongly recommended to obtain a CA certified TLS certificate and create a secret for every host manually as shown below:
  1. Obtain a CA certified TLS certificate for the given host asi.ingress.host in the form of key and certificate files.
  2. Create a secret from the above key and certificate files by running the following command:
    
kubectl create secret tls <Release-name>-asi-ingress-secret --key 
<file containing key> --cert <file containing certificate> -n <namespace>
  3. Use the created secret as the value of the parameter asi.ingress.ssl.secretname.
  4. Repeat the steps for ac.ingress.host and api.ingress.host.

With Kubernetes Service

  • ingress.enabled - Disable ingress by setting this parameter as false.
  • asi.frontendService.type/ac.frontendService.type/api.frontendService.type - Set to a valid external service type LoadBalancer, NodePort, or ExternalName, if supported by the platform.
    Note: NodePort is not a recommended option, particularly for production environments.
  • asi.frontendService.extraPorts/ac.frontendService.extraPorts/api.frontendService.extraPorts - Configure additional ports for the frontend service as individual port mappings with the following port configuration options in values.yaml:
    • name: name for the port mapping.
    • port: service port number.
    • targetPort: target pod port name or number.
    • nodePort: service node port number. Applicable only for service type node port.
    • protocol: valid protocol for the container environment. Defaults to TCP.
  • asi.externalAccess/api.externalAccess – Configure application external access from within application client side tools like GBM and user interfaces. With ingress disabled, the externalAccess configurations must be configured with the LoadBalancer or NodePort public IP address. The following must be configured in values.yaml:
    • asi/api.externalAccess.protocol: HTTP or HTTPS based on LoadBalancer and application internalAccess configurations.
    • asi/api.externalAccess.address: LoadBalancer or NodePort public IP address.
    • asi/api.externalAccess.port: The default value is frontendService HTTP or HTTPS port, if not specified.
  • asi.internalAccess/api.internalAccess – Access the application endpoint on the HTTPS port through LoadBalancer. This ensures end to end secure access to the application. The following configurations must be set as shown below:
    • asi/api.internalAccess.enableHttps: Enable this configuration to access the application on the HTTPS port.
    • asi.internalAccess.httpsPort: If not specified it defaults to .Values.setupCfg.basePort + 1. In case the application war files are deployed on HTTP Server Adapter with TLS enabled, this can be set to the port configured for the adapter.

Annotating custom routes for applications deployed on HTTP Server Adapter (v6.1.0.3 and later versions)

When installing Sterling Secure Proxy outside of the Red Hat OpenShift cluster, where Sterling B2B Integrator is running, Sterling Secure Proxy must forward the incoming requests to the necessary routes created for any custom applications deployed over HTTP Server Adapter. In this case, you must disable the cookies generated by the OpenShift routes, and suitably annotate them.

You can annotate the routes using the following attributes:

haproxy.router.openshift.io/disable_cookies true
haproxy.router.openshift.io/balance source
You can use the following commands to annotate the routes:

oc annotate route <name of route> --overwrite haproxy.router.openshift.io/disable_cookies=true
oc annotate route <name of route> --overwrite haproxy.router.openshift.io/balance=source

Alternatively, you can use the OpenShift console UI to modify the annotations. Go to Networking > Routes. Open the routes created to access your custom application and modify the annotations, as required.