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:

Active-Passive 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 traditional and conservative 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 consistency 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

Active-Passive 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