Deploy for High Availability

Deploying API7 Gateway for high availability (HA) eliminates single points of failure in both the control plane (CP) and data plane (DP). This guide covers the prerequisites, architecture, and step-by-step instructions for deploying a production-grade HA setup.

For a conceptual overview, see High Availability.

This page explains how to deploy an HA topology. After the deployment is in place, use the configure-and-manage guides for ongoing operations:

• Scale Data Plane
• Autoscale Data Plane on Kubernetes
• Data Plane High Availability
• Data Plane Resilience

Architecture Overview

A high-availability deployment consists of:

• Multiple CP nodes (Dashboard + DP Manager) sharing a PostgreSQL database, fronted by a load balancer.
• Multiple DP nodes in one or more Gateway Groups, fronted by a load balancer.
• (Optional) A backup gateway node that periodically exports configuration to external storage (AWS S3 or Azure Blob Storage) for data plane resilience during CP outages.

Prerequisites

Minimum Hosts

Component	Minimum Nodes	Notes
Control Plane	2	Each runs Dashboard + DP Manager
Data Plane	2	Each runs API7 Gateway
PostgreSQL	Managed or HA cluster	HA configuration is out of scope; see PostgreSQL HA

Hardware Requirements

Component	CPU	Memory	Disk
Control Plane	4 Cores	8 GB	40 GB
Data Plane	4 Cores	8 GB	20 GB

For detailed requirements, see System Requirements.

Network Ports

Ensure the following ports are accessible between components:

Service	Port	Protocol	Description
Dashboard	7080 / 7443	HTTP / HTTPS	Dashboard UI and Admin API
DP Manager	7900 / 7943	HTTP / HTTPS	Data plane management
Gateway (HTTP)	9080	HTTP	API traffic
Gateway (HTTPS)	9443	HTTPS	API traffic
Gateway Status	7085	HTTP	Health check endpoint
PostgreSQL	5432	TCP	Database
Prometheus	9090	HTTP	Metrics (optional)

Control Plane HA

The API7 Dashboard and DP Manager are stateless applications that store all configuration in PostgreSQL. Deploy multiple instances behind a load balancer for HA.

Kubernetes (Helm)

Scale the control plane by setting replica counts in your Helm values:

values.yaml

dashboard:
  replicaCount: 2
dp_manager:
  replicaCount: 2

postgresql:
  builtin: false
   
dashboard_configuration:
  database:
    dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

dp_manager_configuration:
  database:
    dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

❶ Deploy at least 2 Dashboard replicas for redundancy.
❷ Deploy at least 2 DP Manager replicas.
❸ Disable the built-in PostgreSQL and point to your external HA PostgreSQL cluster.

Install or upgrade the Helm release:

helm upgrade --install api7ee3 api7/api7ee3 -f values.yaml -n api7 --create-namespace

Docker

On each CP host, run both the Dashboard and DP Manager containers.

Dashboard (dashboard-config.yaml):

dashboard-config.yaml

server:
  listen:
    host: "0.0.0.0"
    port: 7080
database:
  dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

docker run -d --name api7-dashboard \
  -p 7080:7080 \
  -v $(pwd)/dashboard-config.yaml:/app/conf/config.yaml \
  api7/api7-ee-3-integrated:latest

DP Manager (dp-manager-config.yaml):

dp-manager-config.yaml

server:
  listen:
    host: "0.0.0.0"
    port: 7900
database:
  dsn: "postgres://api7ee:$DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

docker run -d --name api7-dp-manager \
  -p 7900:7900 \
  -v $(pwd)/dp-manager-config.yaml:/app/conf/config.yaml \
  api7/api7-ee-dp-manager:latest

Deploy a load balancer (for example, NGINX or HAProxy) in front of the CP hosts to distribute traffic across Dashboard and DP Manager instances.

tip

All Dashboard and DP Manager instances must connect to the same PostgreSQL database. PostgreSQL HA (primary-replica, Patroni, or managed services like Amazon RDS, Azure Database, or Google Cloud SQL) is a separate concern and should be configured according to your database provider's documentation.

Data Plane HA

Data plane nodes are stateless — they receive configuration from the control plane and process traffic independently. Deploy multiple nodes behind a load balancer.

Health Check Configuration

Each gateway node exposes a status endpoint for health monitoring:

Endpoint	Method	Description
/status	GET	Returns 200 if the gateway is running
/status/ready	GET	Returns 200 if the gateway is ready to accept traffic

The status endpoint listens on port 7085 by default. Configure your load balancer to perform health checks against this endpoint at regular intervals (for example, every 10–30 seconds).

Deploy Multiple DP Nodes

Kubernetes (Helm)

Scale data plane replicas using the gateway Helm chart:

gateway-values.yaml

replicaCount: 3

# Pod disruption budget for rolling updates
podDisruptionBudget:
  enabled: true
  minAvailable: 1

# Anti-affinity to spread pods across nodes
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app
                operator: In
                values:
                  - api7-gateway
          topologyKey: kubernetes.io/hostname

Docker

Run gateway containers on multiple hosts. Each connects to the DP Manager for configuration:

docker run -d --name api7-gateway \
  -p 9080:9080 \
  -p 9443:9443 \
  -v $(pwd)/gateway-config.yaml:/usr/local/apisix/conf/config.yaml \
  api7/api7-ee-3-gateway:latest

Deploy a load balancer in front of all gateway hosts. Configure health checks to poll http://<host>:7085/status and remove unhealthy nodes from the pool.

For details on health checks and resilience behavior, see Data Plane High Availability.

Data Plane Resilience (Fallback CP)

For environments that require the data plane to survive extended control plane outages, configure Fallback CP. This feature periodically exports all gateway configuration to external storage (AWS S3 or Azure Blob Storage), enabling data plane nodes to fetch configuration from storage when the control plane is unreachable.

For detailed setup instructions, see Data Plane Resilience.

Verification

After deploying the HA setup, verify each component:

1. Control Plane: Access the Dashboard through the load balancer URL. Confirm that both instances are serving requests by checking access logs on each node.

2. Data Plane: Send a test request through the DP load balancer:

   curl -i "http://<dp-load-balancer>:9080/"

3. Health Checks: Verify the status endpoint on each DP node:

   curl -i "http://<dp-node>:7085/status"
   # Expected: HTTP/1.1 200 OK

4. Failover Test: Stop one CP node and verify the Dashboard remains accessible through the load balancer. Stop one DP node and verify API traffic continues to flow through the remaining nodes.

Next Steps

• Scale Data Plane: Adjust the number of data plane nodes based on traffic.
• Autoscale Data Plane on Kubernetes: Use HPA to scale Kubernetes deployments automatically.
• Data Plane Resilience: Configure fallback storage for extended CP outages.
• Production Best Practices: Harden your deployment for production workloads.
• System Requirements: Review hardware and software requirements.