Offline Resilience
Temporary control-plane connectivity loss separates the live traffic path from management workflows. A running AISIX gateway can keep serving from its latest accepted configuration while it reconnects, but it cannot receive new resources and some AISIX Cloud services remain connectivity-dependent.
Offline resilience protects traffic that depends on configuration already held by the gateway. It does not make the control plane optional or make external upstreams available during their own outages.
Continue Serving Accepted Configuration
After a gateway has applied valid projected configuration, it keeps that snapshot in memory and continues serving it while the configuration connection is unavailable. AISIX does not withdraw the gateway from traffic merely because no newer configuration event has arrived. Use configuration freshness as an operator alert instead of a load-balancer health condition.
No resource changes reach the gateway until connectivity returns. Changes that the control plane accepts during the outage wait for projection and do not affect the snapshot already in service.
Restart from Cached Configuration
In managed mode, AISIX caches the latest accepted snapshot on disk after successful configuration applies. The default path is /var/lib/aisix/config_cache.json; setting managed.snapshot_cache_path to an empty string disables this cache. See AISIX Cloud startup configuration.
A restarted gateway can serve while reconnecting only when that cache is enabled and contains a valid snapshot. AISIX ignores a missing, unreadable, corrupt, or incompatible cache. Without a usable snapshot, /readyz and /status/ready return 503 until the gateway connects and applies valid configuration.
Persist the gateway state directory when a restarted instance must recover its snapshot. Give each gateway instance its own writable state directory rather than sharing one between replicas. The api7/aisix Helm chart uses ephemeral state by default, so a replacement pod must reconnect and obtain configuration before receiving traffic.
Connectivity-Dependent Workflows
The gateway handles control-plane-dependent workflows separately:
| Workflow | Behavior while disconnected |
|---|---|
| Resource projection | New and updated resources do not reach the gateway. The latest accepted snapshot remains in service. |
| AISIX Cloud budgets | AISIX reuses the last decision for up to AISIX_DP_BUDGET_STALE_MAX_SECONDS, which defaults to 600. Without a cached decision, it denies the request. After the stale window, it applies the failure mode returned with the last decision. See Budget Availability and Caching. |
| AISIX Cloud usage telemetry | Failed batches are dropped. AISIX does not persist, retry, or replay them after connectivity returns. Live requests are not failed or delayed to preserve telemetry. |
| External observability exporters | The gateway sends directly to each configured destination, so control-plane loss alone does not interrupt them. Export still depends on connectivity from the gateway to that destination. |
| Heartbeats and certificate rotation | Heartbeat status stops updating. Certificate rotation requires control-plane connectivity; the gateway continues using its current certificate while it remains valid. |
Detect and Recover
A running gateway that is serving a snapshot remains traffic-ready. Check management-path health separately:
GET /status/configreportssource.connected: falseand retains the applied revision and configuration hash.GET /status/readyremains200after a valid configuration has been applied. It is503when a restarted gateway has no usable snapshot.- The
aisix_config_*metrics expose connection state, applied configuration, and load failures for alerting. - AISIX Cloud gateway status becomes stale when heartbeats stop.
See Configuration Status for the complete status fields, metrics, and alert examples. Keep the metrics and status listener private because it is unauthenticated.
To recover, restore DNS, network, and TLS connectivity from the gateway to the AISIX Cloud control-plane endpoint. Confirm that heartbeats resume, compare the published and applied revisions, and send a caller-visible request through the recovered gateway. A successful live request confirms the traffic path, but it does not recover telemetry batches that were dropped during the outage.
Next Steps
Use High Availability for the broader failure-domain design. Use Resource Projection to verify that a recovered gateway applied the expected revision.