# High Availability

Both APISIX Ingress Controller and API7 Ingress Controller support high availability through Kubernetes leader election. With multiple replicas, a standby can take over when the active leader becomes unavailable and resume synchronizing Kubernetes resource changes to the gateway.

## Understand the Availability Model[​](#understand-the-availability-model "Direct link to Understand the Availability Model")

Ingress Controller replicas operate in an active-standby model. Only the replica that holds the leader-election Lease reconciles resources and synchronizes configuration to the gateway. Additional replicas remain ready to acquire the Lease; they do not increase reconciliation throughput.

Gateway traffic does not pass through the Ingress Controller. If the leader becomes unavailable, the gateway can continue serving its last applied configuration, but new or changed Kubernetes resources are not synchronized until another replica becomes the leader.

This deployment protects the Ingress Controller reconciliation process. Configure the gateway, Kubernetes control plane, and API7 control plane or APISIX Admin API for their own availability requirements.

## Configure Multiple Replicas[​](#configure-multiple-replicas "Direct link to Configure Multiple Replicas")

Deploy at least two controller replicas. Both controllers provide a dedicated Helm chart with the same replica value path:

| Ingress Controller        | Dedicated Helm chart               | Replica value path    |
| ------------------------- | ---------------------------------- | --------------------- |
| APISIX Ingress Controller | `apisix/apisix-ingress-controller` | `deployment.replicas` |
| API7 Ingress Controller   | `api7/api7-ingress-controller`     | `deployment.replicas` |

When installing either controller from its dedicated chart, add the following setting to the values file:

values.yaml

```
deployment:

  replicas: 2
```

APISIX Ingress Controller can also be installed by the `apisix/apisix` chart. In this installation, nest the same deployment setting under `ingress-controller`:

values.yaml

```
ingress-controller:

  deployment:

    replicas: 2
```

The same paths can be passed as command-line overrides. Use `--set deployment.replicas=2` with either dedicated controller chart. Use `--set ingress-controller.deployment.replicas=2` when APISIX Ingress Controller is installed by the `apisix/apisix` chart.

Apply the values with `helm upgrade`, or update the source repository if a GitOps controller manages the release. See [Helm Charts](https://docs.api7.ai/ingress-controller/reference/helm-charts.md) for installation and value-management guidance.

## Spread Replicas Across Failure Domains[​](#spread-replicas-across-failure-domains "Direct link to Spread Replicas Across Failure Domains")

Multiple replicas can still be scheduled on the same node unless you define placement rules. Use pod anti-affinity so that a single node failure does not stop every controller replica.

The following example requires two replicas installed from either dedicated controller chart to run on different nodes:

values.yaml

```
deployment:

  replicas: 2

  affinity:

    podAntiAffinity:

      requiredDuringSchedulingIgnoredDuringExecution:

        - labelSelector:

            matchLabels:

              app.kubernetes.io/instance: <release-name>

              app.kubernetes.io/name: <controller-app-name>

          topologyKey: kubernetes.io/hostname
```

Replace `<release-name>` with the Helm release name. Set `<controller-app-name>` according to the installation:

* APISIX Ingress Controller dedicated chart: `apisix-ingress-controller`
* API7 Ingress Controller dedicated chart: `api7-ingress-controller`
* APISIX Ingress Controller installed by the `apisix/apisix` chart: `ingress-controller`

If you override the chart's labels, use the labels from the rendered controller Deployment instead.

If APISIX Ingress Controller is installed by the `apisix/apisix` chart, nest the `deployment` block under `ingress-controller`.

Required pod anti-affinity keeps the replicas on separate nodes, but a replica remains Pending if the cluster does not have enough eligible nodes. Confirm that the cluster has sufficient capacity. In a multi-zone cluster, use [topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) with the `topology.kubernetes.io/zone` key to distribute replicas across zones as well.

Set resource requests and limits so that the scheduler can place the controller reliably during load or node recovery. For APISIX Ingress Controller, `deployment.resources` applies to both the controller and ADC containers. For API7 Ingress Controller, configure `deployment.resources` for the controller container and `adc.resources` for the ADC container.

Verify Disruption Budget Rendering

Before enabling a chart's `podDisruptionBudget` option, run `helm template` with the intended values, confirm that rendering succeeds, and verify that the output contains the expected PodDisruptionBudget. Chart templates and supported values can change independently of the Ingress Controller, so the presence of an option in a values file does not guarantee that it renders successfully.

If the chart cannot render the PodDisruptionBudget, leave the option disabled. During voluntary maintenance, drain or upgrade nodes in stages and confirm that one controller replica remains Ready.

A PodDisruptionBudget only limits voluntary disruptions; it does not replace multiple replicas or failure-domain placement.

## Configure Leader Election[​](#configure-leader-election "Direct link to Configure Leader Election")

Helm installations configure and enable leader election by default. Usually, keep the rendered settings.

All replicas in one logical controller deployment must use the same leader-election ID. If you intentionally run separate controller deployments in the same namespace, give each deployment a unique ID and configure it to reconcile a non-overlapping set of resources. Otherwise, the deployments can suppress or conflict with one another.

Leader election coordinates replicas of one controller; separate election IDs do not isolate their gateway configurations. For API7 Ingress Controller, separate controller deployments must also target different gateway groups through their GatewayProxy resources. If several teams need to add routes to one group, use one controller owner and share its Gateway or IngressClass instead. See [Assign One Owner to Each Gateway Group](https://docs.api7.ai/ingress-controller/set-up-ingress-controller-and-gateway.md#assign-one-owner-to-each-gateway-group).

When you manage `config.yaml` directly, use snake\_case field names. The following example uses valid timing values:

config.yaml

```
leader_election_id: apisix-ingress-gateway-leader

leader_election:

  lease_duration: 30s

  renew_deadline: 20s

  retry_period: 2s

  disable: false
```

Keep leader election enabled when more than one replica is deployed.

The effective values come from the `config.yaml` mounted in the running pod, which can differ from both the controller's built-in defaults and the Helm input values. After applying timing overrides through Helm, inspect the mounted file and confirm that it contains the intended snake\_case fields and values. If the fields are absent or rendered under different names, the controller uses its built-in timing values. Follow [View the Rendered Controller Configuration](https://docs.api7.ai/ingress-controller/reference/helm-charts.md#view-the-rendered-controller-configuration) to inspect the effective file.

The effective `lease_duration` is the main bound on involuntary failover. After the last successful renewal, a ready standby normally takes over after the Lease expires, plus an acquisition retry interval and Kubernetes API latency. Pod scheduling time affects how quickly the Deployment restores its standby capacity; it does not delay takeover when another replica is already Ready.

Shorter values can reduce the failover interval, but they also increase Lease traffic and the risk of leadership changes during API-server or network latency. Test any tuning under representative failure conditions. The controller requires `lease_duration` to be greater than `renew_deadline`, and `renew_deadline` to be greater than `retry_period` multiplied by 1.2. Invalid combinations prevent the controller from starting.

## Verify High Availability[​](#verify-high-availability "Direct link to Verify High Availability")

First, confirm that the Deployment has the intended number of available replicas and that the pods run in different failure domains:

```
kubectl get deployment <deployment-name> -n <namespace>

kubectl get pods -n <namespace> -o wide
```

In a namespace with many workloads, add the label selector from the rendered controller Deployment to the second command.

Next, identify the controller Lease. Use the effective `leader_election_id` from the rendered `config.yaml` as `<leader-election-id>`. List the Lease resources rather than assuming a generated name:

```
kubectl get leases -n <namespace>
```

Inspect the controller Lease to record its current holder, renewal time, and transition count:

```
kubectl get lease <leader-election-id> -n <namespace> -o yaml
```

The relevant fields are `spec.holderIdentity`, `spec.renewTime`, and `spec.leaseTransitions`.

Test failover only in a non-production environment or an approved maintenance window. Watch the Lease in one terminal:

```
kubectl get lease <leader-election-id> -n <namespace> --watch
```

In another terminal, resolve the pod name from `holderIdentity` and delete the leader pod. The value contains the pod name followed by an underscore and a unique suffix:

```
LEADER_HOLDER=$(kubectl get lease <leader-election-id> -n <namespace> \

  -o jsonpath='{.spec.holderIdentity}')

kubectl delete pod "${LEADER_HOLDER%%_*}" -n <namespace>
```

Confirm that the Lease holder changes, the replacement pod becomes Ready, and the Deployment returns to its desired replica count. Direct pod deletion is a failure simulation and is not restricted by a PodDisruptionBudget.

Finally, create or update a test route and send a request through the gateway. This confirms that the new leader resumed configuration synchronization instead of only acquiring the Lease. See [Proxy Requests to a Service](https://docs.api7.ai/ingress-controller/proxy-requests-to-a-service.md) for a complete test route and request.

If the Lease changes but gateway configuration does not update, follow [Troubleshoot Manifest Translation and Synchronization](https://docs.api7.ai/ingress-controller/troubleshooting/configuration-synchronization.md).

## Monitor Availability[​](#monitor-availability "Direct link to Monitor Availability")

Monitor the following signals:

* The controller Deployment has fewer available replicas than its desired count.
* Controller pods remain Pending or restart repeatedly.
* The leader-election Lease stops renewing.
* Configuration synchronization reports errors.

Together, these signals help distinguish a scheduling or leader-election failure from a downstream gateway or control-plane problem.
