HA Redundancy
Server redundancy runs two controller hosts as an active–passive pair. Only one host owns the site’s floating VIP (the address devices and clients use). If the active host fails, the standby promotes so control, automation, and cloud identity continue with minimal interruption.
Purpose
| Goal | Behavior |
|---|---|
| Survive hardware / OS failure | Standby takes the VIP and becomes writable |
| One LAN identity | Devices keep talking to the same VIP (server_unicast_ip) |
| Shared configuration | PostgreSQL streams to the replica; license state fails over with the DB |
| Avoid split-brain | Only the VIP owner runs LAN listeners, Celery beat, and cloud egress |
This is not active–active (two writers on the same VIP) and not a substitute for multiple controllers on a large campus.
Field LAN / clients / devices
│
floating VIP
│
┌────────────┴────────────┐
│ │
PRIMARY (active) SECONDARY (standby)
Compose + listeners ON demoted / listeners OFF
Postgres PRIMARY Postgres REPLICA
Setup
1. Install the primary
Install normally with a Platform one-time install code. Prefer pinning the same RELEASE_TAG / HOST_CONTROLLER_TAG you will use on the secondary.
2. Configure VIP and enable HA on the primary
On the primary (management UI):
- Open Settings → Redundancy.
- While HA is off, set the VIP address (the address programmed on devices).
- Enable HA and copy the join token (you can rotate it later).
3. Install the secondary
On the second host, join as standby:
curl -fsSL https://aida-platform.com/controller/install.sh | sudo bash -s -- \
--secondary \
--primary=<primary-management-ip-or-url> \
--token=<join-token> \
--vip=<floating-vip>
Use the same image tags as the primary. The secondary registers with the primary host-controller, demotes its app listeners, and prepares to take over when needed.
4. Verify
On Settings → Redundancy (prefer viewing from the VIP / active host), confirm:
- One host Active, peer Standby
- Versions match
- Postgres replica lag is healthy
- No Split-brain suspected warning
Usage
| Control | What it does |
|---|---|
| Status | Role (Active / Standby / Standalone / Degraded), peer health, lag, version match |
| Join token | Copy or rotate for secondary install / rejoin |
| Switch Role | Planned failback: checks readiness, yields VIP to the peer, rejoins as replica |
| Auto Fail Back | Preferred primary can reclaim VIP after cooldown when healthy as a demoted replica |
| Disable redundancy | Tear down the pair; survivor remains a sole controller |
| VIP address | Change only while HA is off, then re-enable and rejoin the secondary |
| HA log | Switch, auto-failback, rejoin, gate reject, disable, set-VIP events |
Software updates: use System → Software → Update pair when a secondary is registered so both nodes stay aligned (standby updates first where applicable).
Unplanned failover
If the active host loses keepalived / VIP ownership, the standby promotes automatically (VIP moves, Postgres promotes, services start). Default lab/production policy is often nopreempt: the VIP stays on the survivor until you Switch Role or auto-failback returns it.
Split-brain
If the UI reports Split-brain suspected:
- Demote the host that should not own the VIP.
- Confirm only one host has the VIP and only one Postgres is writable.
- Rejoin the loser as a replica before enabling listeners again.
Do not promote both hosts.
Licensing and cloud
- License state lives in Postgres and streams to the replica — after promote you typically do not re-apply the blob.
- Only the VIP owner opens IoT / remote tunnel egress.