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

Before you deploy, plan the surrounding infrastructure that keeps the cluster available during failures:

• An external PostgreSQL deployment with its own HA or managed failover strategy.
• A load balancer in front of the control plane and another in front of the data plane.
• TLS certificates for API7 Dashboard and DP Manager endpoints, plus mTLS certificates for data plane nodes.
• A maintenance process that restarts one node at a time and verifies traffic before moving on.

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

Deployment Checklist

Complete the following preparation work before you install or scale any HA nodes:

1. Provision an external PostgreSQL instance or cluster and confirm that automatic failover is handled outside API7 Gateway.
2. Reserve stable DNS names or virtual IPs for the control plane and data plane load balancers.
3. Prepare TLS certificates for the Dashboard and DP Manager endpoints. If data plane nodes connect over mTLS, also prepare the CA and node certificates required by your deployment flow.
4. Confirm that every control plane node uses the same PostgreSQL DSN and that every data plane node connects to the same gateway group through the same DP Manager endpoint.

Minimum Hosts

Hardware Requirements

For detailed requirements, see System Requirements.

Network Ports

Ensure the following ports are accessible between components:

Load Balancers and TLS

For production HA, give each traffic path a stable frontend:

On Kubernetes, the control plane chart already creates separate Services for the Dashboard and DP Manager. A common pattern is to keep dashboard_service.type: ClusterIP and expose the Dashboard through an Ingress or internal proxy, while keeping dp_manager_service as a stable internal endpoint. If data plane nodes connect from outside the cluster, expose the DP Manager through an internal load balancer or another stable private frontend.

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.

All control plane replicas must share:

• The same PostgreSQL database.
• The same license state and Dashboard configuration.
• Stable endpoints for operators and data plane nodes.

dashboard:
  replicaCount: 2
dp_manager:
  replicaCount: 2

postgresql:
  builtin: false

dashboard_service:
  type: ClusterIP

dp_manager_service:
  type: ClusterIP

dashboard_configuration:
  database:
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@your-pg-ha-endpoint:5432/api7ee"

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

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

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

docker run -d --name api7-dashboard \
  -p 7080:7080 \
  -p 7443:7443 \
  -v $(pwd)/dashboard_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro \
  api7/api7-ee-3-integrated:v3.10.7 \
  -c /usr/local/api7/conf/conf.yaml

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

docker run -d --name api7-dp-manager \
  -p 7900:7900 \
  -p 7943:7943 \
  -v $(pwd)/dp_manager_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro \
  api7/api7-ee-dp-manager:v3.10.7 \
  /usr/local/api7/api7-ee-dp-manager -c /usr/local/api7/conf/conf.yaml

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.

For predictable failover behavior, configure the data plane so that:

• Each node belongs to the same gateway group.
• The load balancer only sends traffic to healthy nodes.
• Nodes are distributed across failure domains where possible, such as different hosts, zones, or Kubernetes worker nodes.

Health Check Configuration

Each gateway node exposes a status endpoint for health monitoring:

The status listener ships disabled by default — both in the Docker/binary config.yaml (the status block is commented out) and in the Helm chart (status_endpoint.enabled: false). Enable it (see the Helm example below, or uncomment the status block for Docker/binary installs) so it listens on port 7085, then configure your load balancer to perform health checks against it at regular intervals (for example, every 10–30 seconds).

Use /status when you only need to know that the gateway process is alive. Use /status/ready when you want the load balancer to route traffic only to nodes that still have an available DP Manager connection.

Deploy Multiple DP Nodes

api7ee:
  status_endpoint:
    enabled: true
    ip: 0.0.0.0
    port: 7085

apisix:
  replicaCount: 3

  podDisruptionBudget:
    enabled: true
    minAvailable: 1

  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - gateway
            topologyKey: kubernetes.io/hostname

gateway:
  readinessProbe:
    httpGet:
      path: /status/ready
      port: 7085
  livenessProbe:
    httpGet:
      path: /status
      port: 7085

docker run -d --name api7-gateway \
  -e API7_DP_MANAGER_ENDPOINTS='["https://your-cp-lb:7943"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=default \
  -e API7_DP_MANAGER_CERT="..." \
  -e API7_DP_MANAGER_KEY="..." \
  -e API7_CONTROL_PLANE_CA="..." \
  -p 9080:9080 \
  -p 9443:9443 \
  api7/api7-ee-3-gateway:3.10.7

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.

Operational Runbook

Use the following checks during acceptance testing and routine maintenance.

Control Plane Failover Test

1. Log in to the Dashboard through the control plane load balancer.
2. Stop or isolate one CP node.
3. Refresh the Dashboard and confirm that the session remains usable.
4. Apply a small configuration change, such as updating a route description, and confirm it succeeds.
5. Restore the failed node and confirm it rejoins the load balancer pool.

Data Plane Failover Test

1. Send repeated requests through the data plane load balancer.
2. Stop or drain one gateway node.
3. Confirm the load balancer health checks mark the node unhealthy.
4. Verify client traffic continues through the remaining gateway nodes without a full outage.
5. Restore the node and confirm it returns to service only after the health check passes.

Rolling Restart Procedure

Perform rolling maintenance one node at a time:

1. Confirm at least one other CP node and one other DP node are healthy before you restart anything.
2. Remove a single node from the load balancer pool or drain it gracefully.
3. Restart that node and wait until it is healthy again.
4. Verify Dashboard access or gateway traffic before moving to the next node.
5. Repeat for the remaining nodes.

Never restart all control plane nodes or all data plane nodes at the same time unless you have planned downtime.

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.