AIC High Availability

API7 / APISIX Ingress Controller supports high availability through leader election. When running multiple controller replicas, only the leader instance actively processes Kubernetes resources and configures the gateway. This prevents configuration conflicts and ensures automatic failover when the leader becomes unavailable.

Leader Election

The controller uses Kubernetes Lease resources for leader election. When multiple replicas are deployed, they coordinate to elect a single leader. Only the leader performs configuration synchronization.

In the controller's configuration file, you will find leader election related configuration:

config.yaml

leader_election_id: "apisix-ingress-controller-leader"        # The leader election ID for the Ingress Controller.
leader_election:
  lease_duration: 30s          # lease_duration is the duration a non-leader waits after the last observed
                               # leadership renewal before attempting to take over leadership.
  renew_deadline: 20s          # renew_deadline is the time in seconds that the acting controller
                               # will retry refreshing leadership before giving up.
  retry_period: 2s             # retry_period is the time in seconds that the acting controller
                               # will wait between tries of actions with the controller.
  disable: false               # Whether to disable leader election

For environments requiring faster failover, you can reduce these values:

config.yaml

leader_election:
  lease_duration: 10s
  renew_deadline: 7s
  retry_period: 1s

Reducing leader election durations decreases failover time by allowing candidates to detect and replace an unavailable leader more quickly. However, shorter durations increase the frequency of lease renewals and retry attempts, thereby increasing load on the Kubernetes API server and the risk of leader flapping under unstable network or resource conditions.

Multiple Replicas

By default, the controller is deployed with a single replica. To enable high availability, deploy at least two replicas so that leader election can occur and a standby instance can take over if the active leader becomes unavailable.

You can configure the replica count in the Helm values file:

values.yaml

deployment:
  replicas: 2

Alternatively, you can override the value during installation or upgrade using the Helm --set flag:

--set ingress-controller.deployment.replicas=2

See Helm Charts for more information.

Verify Leader Election

You can confirm that leader election is functioning correctly by inspecting the Lease resource and testing failover behavior.

View the Lease resource to see the current leader:

kubectl get lease apisix-ingress-controller-leader -n <namespace> -o yaml

The holderIdentity field in the Lease resource indicates the current leader. If the leader pod is terminated, a new leader is automatically elected.

To validate failover behavior, simulate a leader failure by deleting the current leader pod:

kubectl delete pod -n <namespace> <leader-pod-name>

The remaining replica should automatically acquire leadership through the leader election process. A new leader is usually elected within a few retry cycles. Verify that a new leader has been elected:

kubectl get lease apisix-ingress-controller-leader -n <namespace> -o yaml

Confirm that the holderIdentity field in the Lease resource reflects the newly elected leader.