Kong plugin for wrapping all proxy calls with a circuit-breaker
kong-circuit-breaker
is a Kong plugin that provides circuit-breaker functionality at the route level. It uses lua-circuit-breaker library internally to wrap proxy calls around a circuit-breaker pattern. The functionality provided by this plugin is similar to libraries like resilience4j in Java.
In high throughput use cases, if an API of an upstream service results in timeouts/failures, the following will happen:
The circuit breaker works like an electric circuit breaker only as it has three states:
Internally, the plugin uses lua-circuit-breaker library to wrap proxy calls made by Kong with a circuit-breaker.
window_time
seconds.min_calls_in_window
.failure_percent_threshold
circuit is opened. This prevents any more calls to this route until wait_duration_in_open_state seconds
have elapsed. After this, the circuit transitions to the half-open state automaticallytotal_requests
>= half_open_min_calls_in_window
, failure % is calculated to resolve circuit-breaker into the open or the closed state.wait_duration_in_half_open_state
seconds, it automatically transitions into the closed state.luarocks install kong-circuit-breaker
You will also need to enable this plugin by adding it to the list of enabled plugins using KONG_PLUGINS
environment variable or the plugins
key in kong.conf
export KONG_PLUGINS=circuit-breaker
OR
plugins=circuit-breaker
Clone this repo and run:
luarocks make
conf = {
version = 0,
window_time = 15,
min_calls_in_window = 20,
api_call_timeout_ms = 500,
failure_percent_threshold = 51,
wait_duration_in_open_state = 15,
wait_duration_in_half_open_state = 180,
error_status_code = 599
}
You can add this plugin on a global / service / route level in Kong API Gateway.
conf.excluded_apis
.GET /test
), then enable this plugin for GET /test
route also with a different conf.Key | Default | Type | Required | Description |
---|---|---|---|---|
version | 0 | number | true | Version of plugin’s configuration |
window_time | 10 | number | true | Window size in seconds |
api_call_timeout_ms | 2000 | number | true | Duration to wait before request is timed out and counted as failure |
min_calls_in_window | 20 | number | true | Minimum number of calls to be present in the window to start calculation |
failure_percent_threshold | 51 | number | true | % of requests that should fail to open the circuit |
wait_duration_in_open_state | 15 | number | true | Duration(sec) to wait before automatically transitioning from open to half-open state |
wait_duration_in_half_open_state | 120 | number | true | Duration(sec) to wait in half-open state before automatically transitioning to closed state |
half_open_min_calls_in_window | 5 | number | true | Minimum number of calls to be present in the half open state to start calculation |
half_open_max_calls_in_window | 10 | number | true | Maximum calls to allow in half open state |
error_status_code | 599 | number | false | Override response status code in case of error (circuit-breaker blocks the request) |
error_msg_override | nil | string | false | Override with custom message in case of error |
response_header_override | nil | string | false | Override “Content-Type” response header in case of error |
excluded_apis | ”{"GET_/kong-healthcheck": true}” | string | true | Stringified json to prevent running circuit-breaker on these APIs |
set_logger_metrics_in_ctx | true | boolean | false | Set circuit-breaker events in kong.ctx.shared to be consumed by other plugins like logger |
window_1 ( 0s - 10s ),
window_2 ( 10s - 20s ),
window_3 ( 20s - 30s ) ...
min_calls_in_window
taking total nginx workers into account.min_calls_in_window
to start calculations; else, you may open the circuit when total_requests are relatively low.half_open_max_calls_in_window
to prevent allowing too many requests to the route in the half-open state.set_logger_metrics_in_ctx
sets circuit_breaker_name, upstream_service_host and circuit_breaker_state in kong.ctx.shared.logger_metrics.circuit_breaker
. You can later use this data within context of a request to log these events.version
helps in recreating a new circuit-breaker object for a route if conf_new.version > conf_old.version
, so whenever you change the plugin configuration, increment the version for changes to take effect.