Hyperswitch high availability

The Hyperswitch docs include a self-hosting guide for AWS, so the Helm chart and Kubernetes objects for router and scheduler replicas follow the upstream pattern. The cloud-specific work sits in the data tier and the storage layer: you decide whether PostgreSQL and Redis run in-cluster or as managed services, and you confirm how the cluster spreads across availability zones.

What to decide and confirm:

• PostgreSQL: Compare a self-managed primary and replica against a managed PostgreSQL offering. Confirm the managed service supports the PostgreSQL version and replication setup Hyperswitch needs, and that failover behavior meets your recovery targets. Do not assume a specific service is supported until your team tests it.
• Redis: Confirm whether a managed Redis offering can serve both caching and the scheduler queue, and how it behaves on node or zone loss.
• Zones: Confirm which availability zones your node groups and managed services use, and whether router and scheduler replicas can be spread across them.
• Storage class: Confirm the default storage class's volume binding mode and whether volumes are zonal, since zonal volumes can pin a pod to one zone.
• Helm values: Check which database and Redis connection values the chart expects and map them to your managed endpoints.

Before go-live, test a node drain and a zone failure in a staging account and record which pods reschedule and how long payments take to recover in your own measurements.

Hyperswitch documents a GCP self-hosting guide built on Helm charts. The router and scheduler layers are the same as elsewhere, so the GCP work centers on which managed database and cache services you substitute, how regional clusters distribute nodes, and how persistent volumes behave.

What to decide and confirm:

• PostgreSQL: Evaluate a managed PostgreSQL option against a self-managed primary and replica. Confirm high availability options, replica promotion behavior and supported PostgreSQL versions with Google Cloud and your Hyperswitch release notes.
• Redis: Confirm whether a managed Redis option meets the caching and scheduler queue needs, and how its failover is configured.
• Regional clusters: Confirm whether your cluster is regional or zonal, and how node pools are placed across zones.
• Storage class: Confirm the persistent disk type, whether it is regional or zonal, and how binding mode affects pod placement after a zone failure.
• Network path: Confirm private connectivity between the cluster and the managed database and cache, and that no payment data path leaves the intended network.

Ask the cloud provider to confirm each managed service behavior in writing for your region, then validate failover in a non-production project.

The Hyperswitch docs include an Azure self-hosting guide. The router and scheduler deployment remains the same Helm-based pattern, so Azure-specific planning focuses on the managed database and cache choices, availability zone support in your region and the storage classes your cluster provides.

What to decide and confirm:

• PostgreSQL: Compare a self-managed primary and replica with a managed PostgreSQL service. Confirm the service's high availability mode, failover timing and supported PostgreSQL versions with Microsoft for your region.
• Redis: Confirm whether a managed Redis service can host both caching and the scheduler queue, and how it handles failover and persistence.
• Availability zones: Confirm that your region supports zonal deployment for the cluster, database and cache, since zone support varies by region.
• Storage class: Confirm the default storage class's reclaim policy, binding mode and whether disks are zone-redundant or zonal.
• Identity and access: Confirm how workload identity and secret retrieval are configured for the database and cache credentials the chart uses.

Run a failover rehearsal in a staging subscription before production. Record the observed recovery behavior rather than relying on vendor documentation alone.

A self-managed or air-gapped cluster has no managed database or cache to lean on, so PostgreSQL and Redis become workloads or appliances you operate yourself. The Helm chart and router and scheduler replicas still follow the upstream design, but image mirroring, storage provisioning and zone or rack placement all become your responsibility.

What to decide and confirm:

• PostgreSQL: Choose between a self-managed primary and replica with your own tooling, or an approved enterprise database platform. Confirm replication, automated promotion and backup tooling work without external internet access.
• Redis: Decide whether Redis runs as a replicated set with sentinel-style failover or on a platform your team already supports. Confirm it can serve the cache and scheduler queue within your network.
• Image and chart delivery: Confirm how container images and Helm charts are mirrored into the isolated registry and how updates arrive.
• Storage class: Confirm which storage provider backs persistent volumes, whether it replicates across failure domains, and how volumes behave when a node is lost.
• Failure domains: Confirm how physical racks, hypervisors or data halls map to Kubernetes zone labels, since the cluster can only spread replicas across domains it can see.

Validate every failover path offline, because you cannot rely on a cloud provider's control plane to recover the cluster.

Drain one Kubernetes node that runs Router and Scheduler pods while test payments are in flight. The goal is to confirm that pods reschedule, that in-flight requests either complete or fail in a way the client can retry, and that no scheduled action runs twice when Scheduler Producer or Consumer pods restart.

• Expected behavior: Router replicas on the remaining nodes keep accepting requests. Scheduler work claimed by an evicted pod should become available to another pod once the claim expires or is released. Confirm the claim behavior in your own deployment before the test.
• Signals to record: Ingress 5xx and timeout counts, client retry counts, latency percentiles during the drain, and duplicate scheduled actions, such as a second retry or status sync for the same payment ID.
• Pass criteria: Your team sets them in advance with payment operations. A typical set requires zero duplicate scheduled actions, no payment left in an unknown state after reconciliation, and error rates within a threshold that operations has signed off.
• Fails safely: Requests return errors, clients retry with the same idempotency key, and the payment resolves to a known state.
• Fails incorrectly: A payment is captured twice, a scheduled action runs twice, or a payment stays pending with no later status update.

Confirm that your PodDisruptionBudget and replica counts match the drain scenario, because a drain that the cluster blocks shows nothing about the application.

Simulate the loss of one availability zone by cordoning and removing every node in that zone while traffic continues. This test checks whether Router and Scheduler replicas spread across zones, whether surviving zones have enough capacity, and whether the data layer keeps serving when one of its components sits in the lost zone.

• Expected behavior: Surviving zones absorb Router traffic and pick up Scheduler work. Pods that cannot schedule should show as pending rather than silently reducing capacity without an alert.
• Signals to record: Pending pod counts, error rate by zone, queue depth, and whether any payment requests exceed client timeouts during the scale-up period.
• Pass criteria: Surviving zones handle the test load at the agreed error threshold, no duplicate scheduled actions appear, and the team can name the replica counts and zone spread used in the test.
• Fails safely: Capacity limits cause fast, explicit rejections that clients retry, and no payment is left in an ambiguous state.
• Fails incorrectly: The lost zone holds the only PostgreSQL primary or the only Redis replica, and the system stalls with no alert, or payments are accepted but never processed.

Before running the test, record where each PostgreSQL and Redis instance runs. A zone test that leaves the database primary in the lost zone is a different test, and its result should be filed separately.

Hyperswitch documents a PostgreSQL setup with a master and a replica. This test stops the primary and checks whether the replica is promoted, whether Router and Scheduler reconnect, and whether any committed payment record is lost. The database is the most sensitive component in this test, so the evidence should be reviewed by someone who owns payment reconciliation.

• Expected behavior: Writes fail while promotion happens. Reads may continue on the replica depending on configuration. After promotion, Router and Scheduler reconnect, ideally without a manual restart. Confirm which tool performs promotion, whether it is your database operator or a managed service, and how it fences the old primary.
• Signals to record: Write error counts, connection pool errors, replication lag immediately before the failure, the time until writes succeed again, and any scheduled actions replayed after promotion.
• Pass criteria: No committed payment is missing after promotion, the processor records match internal records in reconciliation, and the replication lag at failure is written down so the data loss window is known.
• Fails safely: Writes are rejected, clients retry with idempotency keys, and reconciliation finds nothing unexpected.
• Fails incorrectly: The old primary accepts writes after the replica is promoted, or a processor shows a capture that has no matching internal record.

Ask the database owner to show that the old primary is fenced before the test starts, because split writes are the failure that reconciliation finds most slowly.

Hyperswitch uses Redis for caching and for the scheduler queue. This test removes a Redis node and checks two separate effects: how much extra load falls on PostgreSQL when the cache is cold, and whether queued scheduler work survives. The second effect matters more for payments, because a lost queue entry can mean a retry or status sync that never happens.

• Expected behavior: Requests slow down as cache misses rise, and PostgreSQL absorbs the extra reads. Queued tasks should either persist through the failover or be recovered from another source. Confirm how your Redis deployment handles persistence and replicas.
• Signals to record: Cache hit ratio, PostgreSQL connection counts and query latency, scheduler queue length before and after the event, and any tasks that were dropped or enqueued twice.
• Pass criteria: Every queued retry or sync either runs or is recorded as failed for follow-up, PostgreSQL stays within the capacity your team measured in advance, and no duplicate actions appear.
• Fails safely: Cache misses slow requests, queued tasks run late, and an alert shows the queue state.
• Fails incorrectly: Queued tasks disappear with no trace, so retries never run, or the same tasks run again after the node returns.

The answer about Redis persistence decides what a Redis loss means for scheduled payment actions, so record that configuration in the test plan before the test begins.

This combined test injects a fault during a rolling Hyperswitch upgrade. Monthly minor releases are common, so teams often perform this sequence more than once a year. The test checks whether the upgrade, the fault and the rollback can happen together without losing payment state. Release notes and the compatibility matrix for Control Center and SDK versions should be reviewed before the test starts.

• Expected behavior: Pods of mixed versions run briefly during the roll. Required dependencies are in place first. For example, the v1.124.0 release notes state that Superposition became a required configuration dependency, and a Superposition service must run before upgrading to that version.
• Signals to record: The version running on each pod over time, migration job status, error counts grouped by version, and any duplicate scheduled actions.
• Pass criteria: The team has tested a rollback, database migrations are backed up or reversible as the release allows, and the fault injection results meet the same thresholds as the single-fault tests.
• Fails safely: The rollout halts, the team rolls back, and traffic stays on the prior version with no unresolved payments.
• Fails incorrectly: Mixed versions write incompatible data, a migration stops partway, or a rollback leaves the database in a state the old version cannot read.

Run this test in a staging environment that matches the production topology, and decide in advance who has authority to stop the upgrade.