Exposing SAP Edge Integration Cell via OpenShift Routes

Updated -

Part of: SAP Edge Integration Cell on Red Hat OpenShift

Table of Contents

Overview

This guide describes how to expose the SAP Edge Integration Cell (EIC) Istio Ingress Gateway using OpenShift Routes. This approach uses the native OpenShift routing layer (HAProxy) for Layer 7 ingress, and can work both with and without an external load balancer in front of the cluster.

Support Scope

[IMPORTANT] Support Scope for OpenShift Routes

While SAP Edge Integration Cell (EIC) can be exposed via OpenShift Routes to accommodate strict on-premise security policies, this configuration differs from the SAP-provided delivery model (which typically relies on LoadBalancer or NodePort services).

  • Red Hat Support: Red Hat validates and supports the OpenShift Route configuration and the underlying ingress infrastructure.
  • SAP Support: SAP support covers the EIC application logic.
  • Customer Responsibility: Any functional limitations, connectivity issues, or feature unavailability resulting specifically from the use of Routes (e.g., inability to support raw TCP without SNI, or loss of source IP preservation) are the responsibility of the customer.

Architectural Differences: Routes vs. LoadBalancer / NodePort Services

When deploying SAP EIC on OpenShift, customers must understand the architectural differences between the Kubernetes service-based approach and the OpenShift Route approach:

Feature NodePort / LoadBalancer OpenShift Route (HAProxy)
OSI Layer Layer 4 (Transport) Layer 7 (Application) & TLS
Protocols TCP, UDP HTTP, HTTPS, TLS (SNI-based TCP)
Client IP Preserved (usually) Not Preserved (Router IP sees traffic)*
Port Usage Service-defined (443 via LB, 30000-32767 via NodePort) Standard ports (80/443)

*Note: The OpenShift Router (HAProxy) acts as a TCP proxy — it creates a new TCP connection to the backend in all termination modes, replacing the original client IP with the router's own IP. In contrast, LoadBalancer services with externalTrafficPolicy: Local preserve the client source IP. Source IP preservation is not available when using Routes.

Traffic Flow with External Load Balancer

In many enterprise on-premise deployments, an external load balancer (e.g., F5, HAProxy, NetScaler) sits in front of the OpenShift cluster. OpenShift Routes support both passthrough and re-encrypt TLS termination — the choice depends on your security requirements and infrastructure setup.

TLS Passthrough

The external load balancer forwards encrypted traffic without terminating TLS. The OpenShift Router uses the SNI header to select the correct Passthrough Route, and the Istio Gateway terminates TLS.

Client → DNS → External LB (L4 Passthrough) → OpenShift Router (Passthrough Route) → Istio Gateway (TLS Termination)
  • DNS: The EIC Virtual Host hostname (e.g., eic.apps.<cluster-domain>) must resolve to the external load balancer's VIP address.
  • External Load Balancer: Must be configured for Layer 4 TCP Passthrough on port 443 — it must not terminate SSL/TLS.
  • OpenShift Router: Must have a Passthrough Route whose spec.host exactly matches the hostname used by clients. The Router uses the SNI header to select the correct Route — if no Route matches, traffic is silently dropped.
  • Istio Gateway (EIC): Receives the encrypted traffic and terminates TLS using the certificates configured in the ELM Keystore.

TLS Re-encryption

The OpenShift Router terminates the client TLS session and opens a new TLS connection to the Istio Ingress Gateway. This allows the Router to inspect headers or enforce policies at the edge while keeping traffic encrypted to the backend.

Client → DNS → External LB → OpenShift Router (Re-encrypt Route) → Istio Gateway (TLS Termination)
  • Route Configuration: Use termination: reencrypt instead of passthrough. The Router needs the backend CA certificate (destinationCACertificate) to trust the Istio Gateway's TLS certificate.
  • Istio Gateway: Must be configured with tls.mode: SIMPLE and a matching hosts entry.
  • Trade-off: mTLS between the client and Istio is not possible with this pattern, since the Router terminates the client TLS session.

Note: If traffic bypasses the OpenShift Router entirely (e.g., an external load balancer performing SSL bridging directly to the Istio Ingress Gateway), OpenShift Routes are not involved. In that case, the load balancer must send the correct Virtual Host hostname via SNI in the new TLS connection.

Edge Termination (Not Supported)

Edge termination (termination: edge) is not compatible with SAP EIC. In this mode, the OpenShift Router terminates TLS and forwards unencrypted HTTP to the backend. The Istio Gateway expects to receive TLS traffic and perform its own TLS termination — sending plaintext HTTP breaks this expectation and causes connection failures.

Common Pitfalls

  • Hostname Mismatch: The Route's spec.host must exactly match the hostname clients use to connect (the Virtual Host configured in EIC). A mismatch causes the Router to drop traffic with no visible error, since SNI-based routing fails silently.

  • Wrong Route Termination Mode: The Route must use termination: passthrough or termination: reencrypt. Using termination: edge or no termination causes the Router to either terminate TLS without re-encrypting to the backend or treat the traffic as unencrypted HTTP — both break the EIC traffic flow.

Operational Restrictions (Route-Based Deployments Only)

The following restrictions apply specifically when using OpenShift Routes to expose the Istio Ingress Gateway. They do not apply to deployments using LoadBalancer services or external load balancers routing directly to Istio:

  • Raw TCP Traffic: OpenShift Routes rely on Server Name Indication (SNI) to route traffic on port 443. Any SAP EIC component or API artifact that uses "Raw TCP" (without TLS/SNI) cannot be exposed via a standard Route on port 443.

  • UDP Traffic: OpenShift Routes do not support UDP traffic. Any feature requiring UDP is unavailable in this topology.

  • Mutual TLS (mTLS): mTLS between the client and the application is supported with the Passthrough Route used in this guide, since the OpenShift Router forwards the TLS connection directly to Istio without terminating it. However, mTLS is not compatible with edge or re-encrypt Routes, where the router terminates the client TLS session.

Optional: Manual Workaround for Route-Based Deployment

In some older EIC releases, the Istio deployment may wait for an external IP assignment when using OpenShift Routes, causing the installation to stall. The latest SAP ELM EIC releases no longer block on this requirement — if possible, upgrade to the latest release to avoid this issue entirely.

If you are on an older release and encounter this stall, you can try the following workaround:

  1. Retry the ELM solution operation if it has failed or timed out.

  2. While the Istio solution is waiting for deployment to complete, manually patch the istio-ingressgateway service to assign the external hostname of your OpenShift Route:

    oc patch svc istio-ingressgateway -n <gateway-namespace> --type='merge' -p '
status:
 loadBalancer:
   ingress:
   - hostname: "eic.apps.<cluster-domain>"
'

    Replace <gateway-namespace> with the namespace where your Istio ingress gateway is deployed (see note below), and eic.apps.<cluster-domain> with your actual Route hostname.

  3. This change allows the Istio deployment to continue by satisfying the external IP/hostname requirement.

Important: This manual patch may be reverted automatically by infrastructure controllers running in the cluster (e.g., Cloud Controller Manager on vSphere/Nutanix/OpenStack, CNI plugins with built-in LoadBalancer capabilities such as Cilium or kube-vip, or ADC operators such as F5 BIG-IP CIS). These controllers watch type: LoadBalancer services and will strip any manually injected status they did not provision. If the patch is being reverted, identify which controller is managing LoadBalancer services in your cluster and either configure it accordingly or upgrade to the latest EIC release.

Namespace Selection

The Route(s) must be created in the same namespace as the istio-ingressgateway service. The namespace depends on your deployment model:

Deployment Model Gateway Namespace
Full Cluster-Admin Access istio-system
Restricted Access (Service Mesh 3.x) istio-gateways

Adjust the metadata.namespace in the YAML examples below accordingly.

DNS Configuration

All Virtual Host hostnames must resolve to the OpenShift Router IP (or the external load balancer VIP, if one is in front of the cluster). When using multiple Virtual Hosts, all hostnames point to the same IP — the OpenShift Router handles the host differentiation via SNI.

Note: Auto-Generated Route from EIC Installation

During EIC installation, a Route named istio-ingressgateway is automatically created in the gateway namespace. This auto-generated Route is not suitable for SAP EIC traffic and should not be used for the Virtual Host configuration. It differs from the required configuration in several ways:

  • No TLS passthrough — the Route has no tls section, so traffic is treated as unencrypted HTTP.
  • Wrong target port — it targets http2 instead of https (port 443 → 8443).
  • Auto-generated hostname — the hostname (e.g., istio-ingressgateway-istio-gateways.apps.<cluster-domain>) does not match the EIC Virtual Host hostname.

You must create your own Passthrough Route(s) as described below, using the correct Virtual Host hostname and TLS passthrough termination. The auto-generated Route can be left in place — it does not interfere with the manually created Routes.

Option A: Single Virtual Host (Default Only)

Use this configuration when SAP EIC is deployed with a single "Default Virtual Host" only.

Step 1: Define the Route

Create a YAML file to define the Route. Below is an example configuration for exposing the Istio Ingress Gateway using passthrough TLS termination.

When you deploy SAP EIC, use a domain like eic.apps. as the "Default Virtual Host".

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: eic-https-route
  namespace: istio-system  # Use 'istio-gateways' for restricted-access deployments
  labels:
    app: istio-ingressgateway
spec:
  host: eic.apps.<cluster-domain>
  to:
    kind: Service
    name: istio-ingressgateway
    weight: 100
  port:
    targetPort: https
  tls:
    termination: passthrough
    insecureEdgeTerminationPolicy: None
  wildcardPolicy: None

Replace with the domain configured during your OpenShift installation, and update namespace if using the restricted-access model.

Step 2: Apply the Route

oc apply -f eic-route.yaml

Step 3: Verify the Route

oc get route -n istio-system   # Use 'istio-gateways' for restricted-access deployments

You should see output similar to the following:

NAME              HOST/PORT                            PATH  SERVICES               PORT    TERMINATION   WILDCARD
eic-https-route   eic.apps.<cluster-domain>                  istio-ingressgateway   https   passthrough    None

Step 4: Test External Access

curl -k --request GET --url https://eic.apps.<cluster-domain>/http/example

Option B: Multiple Virtual Hosts (Default + API)

Use this configuration when SAP EIC is deployed with both a "Default Virtual Host" and an "API Virtual Host" (e.g., for separating runtime and API management traffic).

OpenShift Routes support multiple hostnames on a single Ingress Controller IP using SNI-based routing. Each hostname requires its own Passthrough Route, but both Routes point to the same istio-ingressgateway service. The OpenShift Router reads the SNI header and directs traffic to the correct Route automatically — no additional load balancer configuration is needed.

Step 1: Define Both Routes

Create a YAML file with both Route definitions:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: eic-default-route
  namespace: istio-system  # Use 'istio-gateways' for restricted-access deployments
  labels:
    app: istio-ingressgateway
spec:
  host: eic.apps.<cluster-domain>
  to:
    kind: Service
    name: istio-ingressgateway
    weight: 100
  port:
    targetPort: https
  tls:
    termination: passthrough
    insecureEdgeTerminationPolicy: None
  wildcardPolicy: None
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: eic-api-route
  namespace: istio-system  # Use 'istio-gateways' for restricted-access deployments
  labels:
    app: istio-ingressgateway
spec:
  host: eic-api.apps.<cluster-domain>
  to:
    kind: Service
    name: istio-ingressgateway
    weight: 100
  port:
    targetPort: https
  tls:
    termination: passthrough
    insecureEdgeTerminationPolicy: None
  wildcardPolicy: None

Replace with your cluster domain. Use eic.apps.<cluster-domain> as the "Default Virtual Host" and eic-api.apps.<cluster-domain> as the "API Virtual Host" when deploying SAP EIC.

Step 2: Apply Both Routes

oc apply -f eic-routes.yaml

Step 3: Verify Both Routes

oc get route -n istio-system   # Use 'istio-gateways' for restricted-access deployments

You should see both Routes listed:

NAME                HOST/PORT                                PATH  SERVICES               PORT    TERMINATION   WILDCARD
eic-default-route   eic.apps.<cluster-domain>                      istio-ingressgateway   https   passthrough    None
eic-api-route       eic-api.apps.<cluster-domain>                  istio-ingressgateway   https   passthrough    None

Step 4: Test External Access

Test both Virtual Hosts:

curl -k --request GET --url https://eic.apps.<cluster-domain>/http/example
curl -k --request GET --url https://eic-api.apps.<cluster-domain>/http/example

Comments