Skip to content

Setting Up HAProxy for Oracle REST Data Services (ORDS) with the Oracle Database API for MongoDB

Jump to bottom
Matt DeMarco edited this page Nov 21, 2025 · 9 revisions

Overview

This document provides an example of configuring HAProxy as a load balancer in front of Oracle REST Data Services (ORDS) to support the Oracle Database API for MongoDB.

This configuration is designed to:

  • Load-balance mongosh, MongoDB Compass, and other MongoDB drivers
  • Load-balance ORDS HTTP (8080) and HTTPS (8443) endpoints
  • Provide sticky sessions for MongoDB clients
  • Automatically fail over to a healthy backend if one ORDS server becomes unavailable
  • Provide a real-time monitoring dashboard via the HAProxy stats interface

The result is a resilient, production-ready high-availability configuration for API-driven MongoDB workloads backed by the Oracle Database API for MongoDB.

Prerequisites

Before you begin, ensure that:

  • Each ORDS server is fully running and configured with the Oracle Database API for MongoDB
  • All ORDS servers are reachable on ports 27017, 8080, and 8443
  • You have at least one CentOS/Oracle Linux VM for HAProxy
  • SELinux is configured appropriately for HAProxy (or disabled)

Installing HAProxy on CentOS / Oracle Linux

sudo yum install -y haproxy
sudo systemctl enable haproxy

Validate installation:

haproxy -v

HAProxy Configuration

Copy the configuration below into:

/etc/haproxy/haproxy.cfg

Full Configuration

global
    log /dev/log local0
    maxconn 5000
    daemon

    # Runtime administrative socket (for monitoring)
    stats socket /var/run/haproxy.sock mode 660 level admin
    stats timeout 30s

defaults
    log     global
    mode    tcp
    option  tcplog
    timeout connect 5s
    timeout client  1h
    timeout server  1h

###############################################
# FRONTENDS
###############################################

# MongoDB (mongosh / Compass / Node.js)
frontend fe_mongo_27017
    bind *:27017
    mode tcp
    default_backend be_mongo_27017

# HTTP (port 8080)
frontend fe_http_8080
    bind *:8080
    mode tcp
    default_backend be_http_8080

# HTTPS TLS passthrough (port 8443)
frontend fe_https_8443
    bind *:8443
    mode tcp
    default_backend be_https_8443

###############################################
# BACKENDS
###############################################

# MongoDB backend (with failover + stickiness)
backend be_mongo_27017
    mode tcp
    balance roundrobin

    stick-table type ip size 200k expire 30m
    stick on src

    default-server fall 3 rise 2 on-marked-down shutdown-sessions

    server s1 10.0.0.149:27017 check inter 1s
    server s2 10.0.0.140:27017 check inter 1s
    server s3 10.0.0.214:27017 check inter 1s

# HTTP backend (port 8080)
backend be_http_8080
    mode tcp
    balance roundrobin

    server s1 10.0.0.149:8080 check inter 2s fall 3 rise 2
    server s2 10.0.0.140:8080 check inter 2s fall 3 rise 2
    server s3 10.0.0.214:8080 check inter 2s fall 3 rise 2

# HTTPS backend (port 8443)
backend be_https_8443
    mode tcp
    balance roundrobin

    server s1 10.0.0.149:8443 check inter 2s fall 3 rise 2
    server s2 10.0.0.140:8443 check inter 2s fall 3 rise 2
    server s3 10.0.0.214:8443 check inter 2s fall 3 rise 2

###############################################
# HAProxy STATS + MONITORING DASHBOARD
###############################################

listen stats
    bind *:8404
    mode http
    stats enable
    stats uri /
    stats refresh 5s
    stats show-legends
    stats auth admin:password123

Restart HAProxy with the new configuration:

sudo systemctl restart haproxy

Frontend Configuration Explained

Frontends define how HAProxy listens for incoming connections and which backend they should be routed to.

MongoDB Frontend (Port 27017)

frontend fe_mongo_27017

Defines a frontend responsible for handling all inbound MongoDB wire-protocol connections such as:

  • mongosh
  • MongoDB Compass
  • MongoDB drivers (Node.js, Java, Python, Go, etc.)

bind *:27017

Listens on all network interfaces on port 27017, the default MongoDB port.

mode tcp

Uses raw TCP proxying required for MongoDB’s binary wire protocol.

default_backend be_mongo_27017

Routes all MongoDB client traffic to the backend named be_mongo_27017.

HTTP Frontend (Port 8080)

frontend fe_http_8080

Defines the listener for ORDS HTTP traffic.

bind *:8080

Listens on port 8080, typically ORDS's unsecured HTTP endpoint.

mode tcp

Traffic is forwarded as raw TCP; HAProxy does not inspect or terminate HTTP.

default_backend be_http_8080

Routes HTTP traffic to the backend group for port 8080.

HTTPS Frontend (Port 8443)

frontend fe_https_8443

Handles incoming HTTPS requests for ORDS.

bind *:8443

Listens on all interfaces on port 8443, used for ORDS HTTPS.

mode tcp

Enables TLS passthrough, meaning HAProxy does not decrypt SSL.

default_backend be_https_8443

Forwards encrypted HTTPS connections to backend servers running ORDS on port 8443.

Backend Configuration Explained

Backends define how HAProxy distributes traffic among ORDS nodes, including load balancing, failover, and stickiness behavior.

MongoDB Backend (Port 27017)

backend be_mongo_27017

Defines the backend group that MongoDB clients will be routed to.

mode tcp

Enables raw TCP proxying for MongoDB wire protocol.

balance roundrobin

Distributes new client connections evenly across ORDS servers.

stick-table type ip size 200k expire 30m

Creates a table that tracks clients by IP to support session stickiness:

  • type ip tracks by source IP
  • size 200k supports large workloads
  • expire 30m removes inactive entries after 30 minutes

stick on src

Pins each client’s source IP to a specific backend server to maintain stable MongoDB sessions.

default-server fall 3 rise 2 on-marked-down shutdown-sessions

Controls health and failover behavior:

  • fall 3: mark server DOWN after 3 failed checks
  • rise 2: mark server UP after 2 successful checks
  • on-marked-down shutdown-sessions: terminate active sessions when a node fails so clients reconnect immediately

Backend servers

server s1 10.0.0.149:27017 check inter 1s
server s2 10.0.0.140:27017 check inter 1s
server s3 10.0.0.214:27017 check inter 1s

Each line defines:

  • server name (s1, s2, s3)
  • server IP and port
  • check enables health checks
  • inter 1s checks server health every second

HTTP Backend (Port 8080)

backend be_http_8080

Defines the group of ORDS HTTP servers.

mode tcp

No HTTP inspection—HAProxy forwards traffic directly.

balance roundrobin

Evenly distributes HTTP connections across ORDS servers.

Backend server definitions

server s1 10.0.0.149:8080 check inter 2s fall 3 rise 2
server s2 10.0.0.140:8080 check inter 2s fall 3 rise 2
server s3 10.0.0.214:8080 check inter 2s fall 3 rise 2

Meaning:

  • check server health every 2 seconds
  • mark down after 3 failures
  • mark up after 2 successes

HTTPS Backend (Port 8443)

backend be_https_8443

Handles encrypted HTTPS traffic for ORDS.

mode tcp

Requires TCP passthrough to maintain end-to-end TLS.

balance roundrobin

Distributes TLS connections evenly across ORDS servers.

Backend server definitions

server s1 10.0.0.149:8443 check inter 2s fall 3 rise 2
server s2 10.0.0.140:8443 check inter 2s fall 3 rise 2
server s3 10.0.0.214:8443 check inter 2s fall 3 rise 2

Same health and failover behavior as the HTTP backend.

Testing MongoDB Connectivity Through HAProxy

mongosh "mongodb://matt:xxxx@<HAProxyHost>:27017/matt?authMechanism=PLAIN&authSource=%24external&retryWrites=false&loadBalanced=true&tls=true&tlsAllowInvalidCertificates=true"

Summary

This configuration provides:

  • HAProxy load balancing
  • Sticky sessions
  • Automatic failover
  • TLS passthrough
  • ORDS HTTP/HTTPS balancing
  • Full stats dashboard

Production-ready and compatible with:

  • ORDS
  • Oracle Database API for MongoDB
  • mongosh
  • MongoDB Compass
  • MongoDB drivers

Architecture Diagram

flowchart LR

    subgraph Clients [Clients]
        A1[mongosh]
        A2[MongoDB Compass]
        A3[Node.js Apps]
        A4[REST API Clients - curl, Postman, etc...]
    end

    subgraph LB [HAProxy Load Balancer - Ports 27017 8080 8443]
        LB1[HAProxy, Sticky Sessions, Automatic Failover, Health Checks, Stats Dashboard, TLS Passthrough]
    end

    subgraph Backend [ORDS and Oracle Database API for MongoDB Servers]
        B1[10.0.0.149 ORDS MongoDB API]
        B2[10.0.0.140 ORDS MongoDB API]
        B3[10.0.0.214 ORDS MongoDB API]
    end

    subgraph RAC [Oracle Database 3 Node RAC Cluster]
        R1[RAC Node 1]
        R2[RAC Node 2]
        R3[RAC Node 3]
    end

    %% Client to HAProxy connections
    A1 -->|mongodb 27017| LB1
    A2 -->|mongodb 27017| LB1
    A3 -->|http or https| LB1

    %% HAProxy to ORDS cluster
    LB1 -->|27017 MongoDB| B1
    LB1 -->|27017 MongoDB| B2
    LB1 -->|27017 MongoDB| B3

    LB1 -->|8080 HTTP| B1
    LB1 -->|8080 HTTP| B2
    LB1 -->|8080 HTTP| B3

    LB1 -->|8443 HTTPS| B1
    LB1 -->|8443 HTTPS| B2
    LB1 -->|8443 HTTPS| B3

    %% ORDS systems to Oracle RAC database
    B1 -->|SQL Net| R1
    B1 -->|SQL Net| R2
    B1 -->|SQL Net| R3

    B2 -->|SQL Net| R1
    B2 -->|SQL Net| R2
    B2 -->|SQL Net| R3

    B3 -->|SQL Net| R1
    B3 -->|SQL Net| R2
    B3 -->|SQL Net| R3

    classDef darker fill:#1a1a1a,stroke:#444,color:#fff;
    class LB darker;
    class Backend darker;
    class RAC darker;
Loading

Question/comments/concerns

Appendix – References

Oracle REST Data Services (ORDS)

Oracle Database API for MongoDB

Oracle Database & RAC

HAProxy Documentation

MongoDB Client Connectivity

SELinux and Networking

System Administration & OS Tuning

MongoDB Migration and Setup Guides

  1. MongoDB to Oracle Database API Migration Flow
  2. Setting Up Oracle REST Data Services (ORDS) with the Oracle Database API for MongoDB
  3. Enabling TLS with a Self‐Signed Certificate in ORDS for MongoDB API
  4. ORDS Account Management
  5. Setting Up HAProxy for Oracle REST Data Services (ORDS) with the Oracle Database API for MongoDB

Clone this wiki locally