Configuring SAP Edge Integration Cell with an External Cloud Connector on Red Hat OpenShift

Updated -

Part of: SAP Edge Integration Cell on Red Hat OpenShift

A field-by-field KBA for wiring an external SAP Cloud Connector to an Edge Integration Cell runtime that is deployed on OpenShift behind an Istio ingress gateway. Based on our team's hands-on validation.

Table of Contents

1. Symptom / Scope

This KBA describes how to connect an external SAP Cloud Connector to an Edge Integration Cell (EIC) runtime that runs on Red Hat OpenShift behind an Istio ingress gateway, and how to recover from a specific post-deployment condition we hit during validation: the Operations Cockpit returns HTTP 500 right after the keystore is synced from Integration Suite to the edge runtime, until the affected runtime pods are restarted.

Use this document if you are:

  • Setting up EIC on OpenShift with the External Cloud Connector option (rather than a bundled/embedded connector), and
  • Need the two required Cloud Connector system mappings configured correctly, and
  • Need the exact sequence that clears the Operations Cockpit 500 after the first keystore sync.

All hostnames below are generic placeholders. Substitute your own values:

Placeholder Meaning
api.<cluster-name>.<base-domain>:6443 OpenShift API server endpoint of your cluster
eic-api.<ingress-domain> Internal ingress host that exposes EIC's local (monitoring/OData) API
eic-runtime.<ingress-domain> Internal ingress host where integration flows execute
<scc-virtual-host> A Cloud Connector virtual host (one per mapping — never shared)

2. Environment

  • Red Hat OpenShift Container Platform with an Istio ingress gateway fronting the EIC namespaces (OpenShift Service Mesh / Istio).
  • SAP Edge Integration Cell runtime deployed via SAP Edge Lifecycle Management (ELM / Operations Cockpit).
  • SAP Integration Suite tenant with Edge Integration Cell enabled.
  • External SAP Cloud Connector (on-premise), bound to the relevant BTP subaccount.

3. Prerequisites

Complete the external Cloud Connector prerequisites before starting, as described in:

That Note establishes the groundwork for the K8s API connection (Mapping 1). The points that affect this KBA:

  • Connectivity mode. ELM supports an embedded Cloud Connector (deployed and managed by SAP) or an external one (you install, operate, and update it; SAP support is limited to the ELM side). This KBA covers the external option.
  • kubeconfig authentication. You must provide a kubeconfig that authenticates with a service account token. OIDC tokens, client certificates, and authentication plugins are not supported. Plan to rotate the kubeconfig periodically.
  • Access control. When you configure access control for the Kubernetes API in Cloud Connector, you must select the "Include Resources" checkbox to grant access to all Kubernetes APIs.
  • DNS, not IP. If the Kubernetes API uses a self-signed certificate with the trust check enabled, configure the endpoint with a DNS name — not an IP address. Cloud Connector excludes IP Subject Alternative Names during certificate validation, so an IP endpoint always fails the trust check. (The alternative, disabling the trust check, reduces security.)
  • Reused later. The Virtual Host / Virtual Port you choose for the K8s API mapping, together with the Location ID, are entered again in the ELM Initialize Edge Node step.

Scope note on field values: SAP Note 3685466 configures the K8s API mapping by pointing to the generic Cloud Connector "Configure Access Control" documentation — it does not itself prescribe the Back-end Type or Host in Request Header values. Those cells in §5.1 below are the values our deployment used, not quotes from the Note.

4. Concepts (read before configuring)

The public docs cover two points tersely. Here they are in our own words, from the OpenShift + Istio perspective.

Why EIC needs two separate system mappings

EIC on OpenShift requires two distinct connections through Cloud Connector, serving two unrelated purposes, so they are configured as two separate system mappings and must not share a virtual host:

Mapping Backend it reaches Why it exists
Mapping 1 — Kubernetes (OpenShift) API Server api.<cluster-name>.<base-domain>:6443 Lets Edge Lifecycle Management reach the cluster's Kubernetes API to deploy, manage, and upgrade the EIC runtime.
Mapping 2 — EIC Local API eic-api.<ingress-domain> (via Istio ingress) Lets the Operations Cockpit call the edge runtime's local monitoring/OData API, so runtime data is read at the edge instead of flowing through the cloud.

They address completely different backends (a Kubernetes control-plane endpoint vs. an application API behind Istio). A virtual host identifies one backend on BTP, so reusing the same virtual host for both would collapse two different destinations into one. Keep one virtual host per mapping.

Not a Cloud Connector mapping: the iflow runtime host (eic-runtime.<ingress-domain>) is reached directly through DNS → Istio ingress. It is an EIC solution property, not a Cloud Connector system mapping.

The "Host in Request Header" rule

Cloud Connector can forward either the virtual host or the real internal host in the HTTP Host header. The correct choice depends on whether the backend routes by hostname:

  • Use Internal Host when the backend is host-routed. The EIC Local API (Mapping 2) sits behind the Istio ingress gateway, which selects the route from the Host header. If the virtual host were forwarded, Istio would not match a route. So Mapping 2 forwards the internal host (eic-api.<ingress-domain>).
  • For the Kubernetes API Server (Mapping 1) the backend is not an application router keyed on the Host header, so the setting differs from Mapping 2 — our deployment used Use Virtual Host. SAP Note 3685466 does not prescribe this value; it links to the generic Cloud Connector Configure Access Control documentation (see Mapping 1).

5. Configuration

Configure both mappings in Cloud Connector → Cloud To On-Premise → Access Control. Field names follow the Cloud Connector UI.

5.1 Mapping 1 — Kubernetes (OpenShift) API Server

This mapping lets Edge Lifecycle Management reach the cluster. SAP Note 3685466 sets the prerequisites but delegates the field-level mechanics to the generic Cloud Connector Configure Access Control documentation. The Back-end Type and Host in Request Header values below are the ones our deployment used — they are not prescribed by the Note (see the scope note in §3).

SCC Field Value
Back-end Type Non-SAP System (our deployment; not specified by the Note)
Protocol HTTPS
Internal Host api.<cluster-name>.<base-domain> — use a DNS name, not an IP (per SAP Note 3685466, an IP endpoint fails the trust check)
Internal Port 6443
Virtual Host <scc-virtual-host> (unique — not shared with Mapping 2)
Virtual Port 6443
Allow Principal Propagation Deselect
System Certificate for Logon Deselect
Host in Request Header Use Virtual Host (our deployment; not specified by the Note) — the K8s API server is not an application router keyed on the Host header, so this differs from Mapping 2 (see Concepts)
Check Internal Host Do not select
Include Resources Select — required per SAP Note 3685466 to grant access to all Kubernetes APIs
Resources / — Path and all sub-paths, active

The Virtual Host and Virtual Port here must exactly match the Cloud Connector connectivity details (plus Location ID) you enter in the ELM Initialize Edge Node wizard. A mismatch means ELM cannot reach the cluster.

5.2 Mapping 2 — EIC Local API

Source (confirmed): Configure an External Cloud Connector for Edge Integration Cell. This mapping targets EIC's local API host only — do not point it at the Kubernetes API server, which is why a second, separate mapping is required.

SCC Field Value
Back-end Type Other SAP System
Protocol HTTPS
Internal Host eic-api.<ingress-domain> ← must match API Virtual Host in §5.3; resolves to your LoadBalancer IP, or to the OpenShift router if you expose the ingress via a Route (see Appendix A)
Internal Port 443
Virtual Host <scc-virtual-host> (a different virtual host than Mapping 1)
Virtual Port 443
Allow Principal Propagation Deselect
System Certificate for Logon Deselect
Host in Request Header Use Internal Host — Istio routes by hostname, so the real ingress host must be forwarded (see Concepts)
Check Internal Host Do not select
Resources /Operations and /api — active, path and all sub-paths

5.3 EIC Solution Properties (Deploy Solution)

Source: Configure an External Cloud Connector for Edge Integration Cell. Set these while deploying the EIC solution from the Operations Cockpit.

EIC Field Value Notes
Default Virtual Host eic-runtime.<ingress-domain> Host where iflows are exposed/executed. Reached directly via Istio ingress — no Cloud Connector mapping.
Default Virtual Host Key Alias (your keystore alias) TLS key-pair alias held in the EIC keystore.
API Virtual Host eic-api.<ingress-domain> Must equal the Internal Host of Mapping 2 (§5.2).
API Virtual Host Key Alias (your keystore alias) TLS key-pair alias held in the EIC keystore. May equal the Default alias.
Cloud Connector Virtual Host <scc-virtual-host>:443 Must equal the Virtual Host : Virtual Port of Mapping 2 — including the port. This is the host:port the cloud side calls through Cloud Connector; if the port here does not match the mapping's Virtual Port, Cloud Connector rejects the call with "Access denied to system … ensure to expose the system correctly in your cloud connector." The virtual port is independent of the backend's internal port — leave Mapping 2's Internal Port at 443.

5.4 Trust Store

Each mapping's backend presents a TLS certificate, so Cloud Connector must trust the CA that signed it. Add the signing CA to the Cloud Connector backend trust store (allowlist) for each mapping:

Mapping CA to add to Cloud Connector trust store
Mapping 1 (K8s API) The CA that signed the OpenShift API server certificate (api.<cluster-name>.<base-domain>).
Mapping 2 (EIC Local API) The CA that signed the eic-api.<ingress-domain> certificate presented by the Istio ingress gateway. Add it as described under Configure Trust in the EIC external Cloud Connector doc.

On OpenShift, the ingress/serving certificates are managed by the platform operators — this step only imports the public CA into the Cloud Connector allowlist. Do not hand-manage the runtime's server certificates.

If you expose the ingress via an OpenShift passthrough Route, TLS still terminates at Istio (the router only forwards by SNI), so this trust configuration is unchanged — only the network path differs. See Appendix A.

6. Post-Deployment Steps (keystore sync + roll-restart)

This is the key finding from our validation. Plan for it — it is expected, not a defect.

After the EIC solution is deployed and the mappings are in place:

  1. Sync the keystore from Integration Suite to the EIC runtime (the standard keystore synchronization step). This pushes the current keystore/certificates to the edge.

  2. Expect an Operations Cockpit HTTP 500 immediately after the sync. In our deployment the runtime pods continued serving with the previously loaded keystore and did not pick up the newly synced material, so the Local API calls behind the sync failed with 500.

  3. Roll-restart the edc workload so it reloads the new keystore/certificate. In our validation the running pods kept serving the old keystore and did not hot-reload the synced material, so a restart was required:

    oc rollout restart deployment/edc -n <eic-namespace>

    A rolling restart lets the workload come up and load the freshly synced keystore while keeping availability during the restart.

    Confirm the exact workload kind and name in your namespace with oc get deploy,statefulset -n <eic-namespace> first; naming and controller type may differ by EIC version.

  4. Re-check the Operations Cockpit. Once the edc pods are Running again, the 500 clears and monitoring data loads.

7. Verification

Confirm the integration end to end:

  1. Cloud Connector — In Cloud To On-Premise → Access Control, both mappings show a reachable backend. Run the built-in connection/reachability check for each mapping; both should report the backend as available and the resource paths as accessible.
  2. Operations Cockpit — The edge node/cluster monitoring views load without HTTP 500, and runtime data (message monitoring, component status) is populated.
  3. Cluster status — The edge cluster reports Available in the Operations Cockpit.

8. Troubleshooting

Symptom Cause Resolution
Operations Cockpit returns HTTP 500 right after a keystore sync The edc workload is still serving the previously loaded keystore and has not picked up the newly synced certificate/keystore. Roll-restart the edc workload so it reloads the new keystore, then re-check the Operations Cockpit. See §6.
ELM cannot reach the cluster during Initialize Edge Node Mapping 1 Virtual Host / Virtual Port does not match the Cloud Connector details entered in the ELM wizard, or the K8s API CA is missing from the trust store. Align Mapping 1's virtual host/port with the wizard, and add the API server CA to the Cloud Connector trust store (§5.4).
Local API calls fail even though the mapping looks correct Mapping 2 is forwarding the virtual host, so Istio cannot match a route. Set Mapping 2 Host in Request Header → Use Internal Host (§5.2).
Access denied to system <virtual-host>:<port> … ensure to expose the system correctly in your cloud connector (e.g. a :8080 seen for the monitoring/local API) The cloud side is calling the virtual host on a virtual port that has no matching Mapping 2 entry — typically a port mismatch between the EIC Cloud Connector Virtual Host property and Mapping 2's Virtual Port. Align them: set the EIC Cloud Connector Virtual Host property to <scc-virtual-host>:443 to match Mapping 2's Virtual Port (§5.3), then update the solution. Do not change Mapping 2's Internal Port — the real backend (Istio ingress) listens on 443; the virtual port is independent of it.
Senders ask "which URL/endpoint do we send to?" Confusion between the runtime path (direct to Istio) and the management path (through Cloud Connector). Senders call the iflow URL endpoint on the Default Virtual Host (eic-runtime.<ingress-domain>), which resolves via DNS directly to the Istio ingress (LoadBalancer IP, or the OpenShift router if exposed via a Route). This is not a Cloud Connector call — Cloud Connector carries only the local API (§5.2) and the K8s API (§5.1). The Route is how the host is exposed, not a separate address (Appendix A).

9. References

Appendix A — Exposing the EIC Ingress: LoadBalancer vs. OpenShift Route

This is orthogonal to Cloud Connector — not an alternative to it. A Route does not replace a Cloud Connector system mapping, and it does not remove the need for Mapping 2.

Two different concerns are easy to conflate:

Concern What it is
Cloud Connector The tunnel from BTP into your network — the management/operations plane. Always required for the external Cloud Connector option.
LoadBalancer vs. OpenShift Route How you expose the Istio ingress gateway inside the cluster — i.e. the backend that Mapping 2's Internal Host and the runtime DNS point at.

An external Cloud Connector is required whether the Istio ingress is exposed via a LoadBalancer service or an OpenShift Route. The choice only changes what the hostnames resolve to.

When to use a Route

Use an OpenShift passthrough Route when a LoadBalancer service is unavailable or undesired (e.g. strict on-premise policies). In that topology:

  • eic-api.<ingress-domain> and eic-runtime.<ingress-domain> resolve to the OpenShift router (or to an external load-balancer VIP sitting in front of it), instead of to a LoadBalancer service IP.

What changes in the configuration above

Nothing in the mapping field semantics. The only differences are:

  • Mapping 2's Internal Host (§5.2) and the runtime DNS now resolve to the Route hostname (the OpenShift router), not to a LoadBalancer IP.
  • Host in Request Header → Use Internal Host (§5.2) becomes even more essential: both the OpenShift router (SNI-based) and Istio route by hostname, so the real ingress host must be forwarded end to end.

The Route (illustrative)

One passthrough Route per exposed host, targeting the istio-ingressgateway service:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: eic-api-route
  namespace: <gateway-namespace>   # e.g. istio-gateways (restricted) or istio-system
spec:
  host: eic-api.<ingress-domain>
  to:
    kind: Service
    name: istio-ingressgateway
  port:
    targetPort: https
  tls:
    termination: passthrough
    insecureEdgeTerminationPolicy: None
  wildcardPolicy: None

Create one such Route per host you expose (eic-api.<ingress-domain>, and eic-runtime.<ingress-domain> if the runtime is also fronted this way).

Two correctness caveats

  1. TLS stays with Istio. With termination: passthrough the OpenShift router forwards by SNI and does not terminate TLS — Istio does. So the Cloud Connector trust store / CA configuration (§5.4) is unchanged; only the network path differs.
  2. The Istio Gateway must declare a listener for that host. If the gateway has no server/host entry matching the Route's hostname, the Route reaches the gateway but Istio drops or 404s on the SNI/host — the Route alone is not enough.

For the full OpenShift Route treatment — single vs. multiple virtual hosts, passthrough vs. re-encrypt, namespace selection, DNS, the auto-generated istio-ingressgateway Route to avoid, and common SNI pitfalls — see Exposing SAP Edge Integration Cell via OpenShift Routes. This appendix only covers what is specific to the external Cloud Connector setup.

Comments