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

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
• You have at least one CentOS/Oracle Linux VM for HAProxy
• SELinux is configured appropriately for HAProxy (or disabled)
• All backend servers are reachable on ports 27017, 8080, and 8443

---

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

---

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]
        A3[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

• Please feel free to contact Matt DeMarco