API Breaker Configuration
The api-breaker plugin opens a circuit after configured upstream failures, returns a controlled response, and allows new requests after a backoff interval. Configuration covers static settings and plugin parameters.
Static Configurations
The gateway stores breaker counters in the plugin-api-breaker shared memory zone. Each gateway instance allocates 10m by default. Increase the zone when a gateway instance must track a large number of host and path combinations.
Shared memory zones are sized when the gateway starts. A full restart is required after changing the size; a reload does not resize an existing zone.
- Host or Docker
- Kubernetes (Helm)
For host or Docker deployments, override the zone in the persistent gateway configuration:
nginx_config:
http:
lua_shared_dict:
plugin-api-breaker: 20m
Restart the gateway for the change to take effect.
For the APISIX Helm chart, set:
apisix:
nginx:
luaSharedDicts:
- name: plugin-api-breaker
size: 20m
For the API7 Gateway Helm chart, set:
apisix:
http:
luaSharedDict:
plugin-api-breaker: 20m
Apply the complete values file with the chart used by the gateway release:
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
Parameters
See plugin common configurations for configuration options available to all plugins.
break_response_code
valid value:
between 200 and 599 inclusiveHTTP status code returned while the circuit is open.
break_response_body
Response body returned while the circuit is open.
break_response_headers
Response headers added while the circuit is open. These headers are added only when
break_response_bodyis configured.key
valid value:
at least 1 characterResponse header name.
value
max_breaker_sec
valid value:
greater than or equal to 3Maximum open-circuit interval in seconds. The interval starts at 2 seconds and doubles after repeated failure thresholds until it reaches this value.
unhealthy
Conditions that record upstream failures and open the circuit.
http_statuses
valid value:
one or more unique values between 500 and 599 inclusiveUpstream response status codes counted as unhealthy.
failures
valid value:
greater than or equal to 1Number of unhealthy responses required to open the circuit.
healthy
Conditions that clear accumulated failure state after matching healthy responses.
http_statuses
valid value:
one or more unique values between 200 and 499 inclusiveUpstream response status codes counted as healthy.
successes
valid value:
greater than or equal to 1Number of healthy responses required to clear the failure state.