Deploy Active/Standby Gateway

Architecture

V1 uses exactly two independently addressable replicas. While connected, one is Active and lease mutations synchronously commit to both encrypted stores. The other is Standby. A Standby returns not_active; a Gateway client retries the other endpoint with the same idempotency key.

flowchart LR
  C[Product installations] --> E[Stable client endpoint or two configured DNS names]
  E --> A[Gateway A: Active]
  E --> B[Gateway B: Standby]
  A <-->|mTLS Raft :9443\nreconciliation :9543| B

Procedure

1. Prepare two hosts, each following prerequisites. Give them distinct ha.replica_id, client addresses, and peer listen addresses; use one shared gateway_id, state-encryption key, and signed license that lists both IDs.
2. Configure node A from the HA A-side example, then derive node B from the B-side delta. On A, peer targets point to B; on B they point to A. Configure mutual TLS peer certificates with each node’s configured peer identity and target SAN.
3. Run node-id for both configurations and obtain the two-node license. Validate each configuration, start both services, then query authenticated GET /v1/ha on each.
4. Configure products with both advertised URLs. A load balancer or VIP is optional; see stable endpoints.

Failure and recovery

After ha.peer_loss_timeout_seconds of peer loss, an isolated node becomes degraded_active and can issue/renew leases. This is not zero-downtime failover: clients must retry a transport failure or not_active response. Both sides of a partition can issue up to their local full capacity, temporarily exceeding licensed capacity. On reconnection, acknowledged leases are reconciled; new acquisition is blocked while merged live grants exceed capacity, while renew, release, and expiry continue.

Only durable lease records and idempotency state are replicated. Configuration, license files, TLS material, state-encryption key, logs, and reports are not. Restore a repaired node with its own configuration and secrets, then start it and verify peer connectivity. See recovery and HA troubleshooting.