Skip to main content

IguanaX HA Designs

Overview​

IguanaX supports multiple HA designs because no single architecture fits all integration workloads.

Different environments have different priorities, such as:

  • Guaranteed message ordering

  • Maximum throughput

  • Full utilization of compute resources

  • Minimal infrastructure cost

  • Operational simplicity

Each IguanaX HA design makes intentional trade-offs between:

  • Availability

  • Data consistency

  • Performance

  • Infrastructure dependency

Understanding these trade-offs is essential before choosing a design.

IguanaX HA Design Options​

IguanaX currently supports the following primary HA patterns:

Instant Failover HA

Concept​

The Instant Failover HA design consists of two independent IguanaX instances running behind a load balancer:

  • Both instances are online and capable of receiving traffic

  • The load balancer routes incoming LLP and HTTP(S) traffic to a healthy instance

  • Each IguanaX instance maintains its own local logs and WorkingDir

High availability is achieved through:

  • Load Balancer → controls inbound traffic routing

  • Poller Manager → ensures only one instance runs polling components

  • Sync Manager → keeps configurations aligned between instances

This design prioritizes near-zero downtime rather than queue recovery or message sequencing.

Why This Design Exists​

This design is intended for environments where:

  • Continuous availability is the top priority

  • Near-zero downtime is required for LLP or HTTP endpoints

  • Upstream systems can retry messages if needed

  • Full queue recovery and strict sequencing are not required

It is commonly used for API-driven or event-driven integrations.

Key Characteristics​

  • Both IguanaX instances are active for inbound traffic

  • Load balancer performs health checks and fast failover

  • Poller Manager ensures only one active poller at a time

  • Sync Manager keeps configurations consistent

  • No shared storage for queues or logs

This design favors availability and performance over strict data consistency.

How HA Components Work Together​

Load Balancer​

  • Routes LLP and HTTP(S) traffic to healthy IguanaX instances

  • Removes failed instances automatically

  • Enables failover within seconds

Poller Manager (HA Tool)​

  • Controls polling components such as:

    • From DB

    • From File / FTP

  • Ensures only one IguanaX instance runs pollers

  • Prevents duplicate message processing

Sync Manager (HA Tool)​

  • Synchronizes configuration changes from primary to secondary:

    • Translator code (Git repository)

    • Component configurations (fields, tags, descriptions)

    • Component connections and workflows

  • Keeps both IguanaX instances functionally aligned

What This Design Requires​

To function correctly, this design requires:

  • Two IguanaX instances (both running and reachable)

  • A load balancer for LLP and HTTP routing

  • Poller Manager to control polling behavior

  • Sync Manager to maintain configuration consistency

  • Reliable heartbeat and health checks between instances

What Is Guaranteed​

  • Near-zero downtime for LLP and HTTP endpoints

  • Fast failover (typically within seconds)

  • Continuous availability of inbound interfaces

  • No duplicate polling (when Poller Manager is used correctly)

Trade-Offs​

  • No queue recovery if an instance fails

  • No guaranteed message sequencing

  • Messages in local queues may be lost or require retry

  • Requires upstream systems to handle retries

Typical Use Cases​

  • HTTP/REST API integrations

  • LLP interfaces where sender supports retries

  • Event-driven architectures

  • High-throughput environments prioritizing uptime

Sequencing & Recovery HA

Concept​

The Active-Passive HA design consists of two IguanaX instances:

  • One Active instance that processes all messages

  • One Passive instance that runs continuously and monitors the Active instance

At any given time, only one instance is responsible for message processing. The Passive instance exists solely to take over when a failure occurs.

Why This Design Exists​

This design is intended for environments where:

  • Message sequencing is critical

  • Queue recovery must be guaranteed

  • Polling components must be tightly controlled to avoid duplicate message processing

It reflects the most reliability-focused HA model used in healthcare integrations.

Key Characteristics​

  • Single Active processing node

  • Automatic failover based on heartbeat and health checks

  • Centralized control of pollers

  • Strong message sequencing and recovery guarantees

Because only one instance processes messages at a time, this design favors correctness and predictability over raw throughput.

What This Design Requires​

To function correctly, this design requires:

  • Two IguanaX instances (Active and Passive)

  • A load balancer to route LLP and HTTP traffic

  • A highly available storage or synchronization mechanism for:

    • Logs

    • Message queues

    • Configuration state

  • Reliable heartbeat and fault detection

What Is Guaranteed​

  • Automated failover on server failure

  • No message loss (under supported configurations)

  • Message processing continues from the correct queue position

  • Message ordering is preserved

Trade-Offs​

  • Only one server actively processes messages at a time

  • Lower overall resource utilization

  • Brief downtime may occur during failover while recovery completes

Typical Use Cases​

  • HL7 interfaces with strict ordering requirements

  • Polling-based integrations (DB, File, FTP)

  • Environments where correctness is more important than throughput

Sequencing & Recovery Multi-Cluster HA

Concept​

The Active-Passive Multi-Cluster design extends the standard Active-Passive model by introducing multiple independent IguanaX clusters.

Each cluster:

  • Has its own Active and Passive instance

  • Operates independently of other clusters

  • Owns its own message queues and configuration state

This allows both production servers to actively process workloads, while still maintaining HA guarantees per cluster.

Why This Design Exists​

In traditional Active-Passive designs, the Passive server may be underutilized.

The Multi-Cluster design addresses this by:

  • Splitting workloads across clusters

  • Allowing each server to be Active for one cluster and Passive for another

  • Increasing overall system utilization without sacrificing HA guarantees

Key Characteristics​

  • Multiple HA domains within the same environment

  • Independent failover per cluster

  • Clear isolation of queues and message ownership

  • Better use of available hardware

What This Design Requires​

This design requires:

  • Two or more IguanaX clusters (for example, WK1 and WK2)

  • A load balancer capable of routing traffic by cluster

  • Dedicated storage or synchronization per cluster

  • Independent heartbeat and failover logic for each cluster

Operational discipline is important to ensure workloads are properly partitioned.

What Is Guaranteed​

  • HA behavior identical to Active-Passive within each cluster

  • Message sequencing and queue recovery per cluster

  • Failover of one cluster does not affect others

Trade-Offs​

  • Increased architectural complexity

  • More planning required for traffic routing and workload assignment

  • Requires clear operational boundaries between clusters

Typical Use Cases​

  • High-throughput environments

  • Large integration platforms with many interfaces

  • Organizations that want both:

    • High availability

    • Efficient server utilization

Each design is described below at a conceptual level.

Choosing the Right HA Design​

There is no “best” HA design—only a design that best fits your requirements.

When choosing an IguanaX HA design, consider:

  • Do you require strict message sequencing?

  • Are polling components involved?

  • Is maximizing throughput more important than simplicity?

  • How much operational complexity can your team support?

  • What infrastructure (storage, load balancing) is available?

These questions should be answered before implementation.

Getting Started​

This document is intended to build conceptual understanding, not replace design consultation.

To design and implement an IguanaX HA solution that fits your environment:

Our team can help you:

  • Select the appropriate HA design

  • Validate infrastructure requirements

  • Plan failover behavior

  • Review operational readiness