Mastering Health Checks in OpenResty: Compare Three Backend Modules

1. ngx_http_upstream_module

OpenResty runs on Nginx, so the built‑in ngx_http_upstream_module can be used for passive health checks. It relies on max_fails and fail_timeout parameters; a worker increments a fail counter when a request to a node fails and marks the node unavailable when the counter exceeds max_fails within fail_timeout. When all nodes are down the fail counters are cleared for fast recovery.

Configuration example:

upstream test-servers {
  server 10.1.1.1:8090 max_fails=1 fail_timeout=3s;
  server 10.1.1.2:8090 max_fails=1 fail_timeout=3s;
}

Parameters description:

max_fails: maximum failures within fail_timeout before the node is considered unavailable.

fail_timeout: time window for counting failures.

Node status can be observed in the error log; the article shows sample logs for successive requests.

2. lua‑resty‑upstream‑healthcheck module

This third‑party module provides active health checks for OpenResty, creating a timer per upstream that periodically sends HTTP requests and evaluates the response code. Node health is stored in shared memory, making it visible to all workers.

Key functions:

spawn_checker – registers the timer and parses configuration.

check – timer entry point.

do_check – performs the health check and updates shared memory.

check_peers_updates – updates worker‑local status.

check_peers – distributes check tasks.

check_peer – sets node status based on HTTP result.

Implementation notes:

Only HTTP checks are supported.

The HTTP request must be supplied by the downstream application.

Each upstream defines its own spawn_checker entry.

OpenResty 1.9.3.2+ includes the module; older versions require manual loading.

3. ngx_upstream_check_module

The nginx_upstream_check_module (used in Taobao Tengine) performs proactive periodic health checks without needing a client request. It creates a timer per node, uses locks and shared memory to coordinate checks, and updates node status globally.

Important functions:

ngx_http_upstream_check_init_process – worker initialization.

ngx_http_upstream_check_begin_handler – timer task.

ngx_http_upstream_check_connect_handler – tests node reachability.

ngx_http_upstream_check_status_update – updates node status.

To use it with OpenResty, the Nginx source must be patched (e.g., applying the 1.11.1 patch to 1.11.2) and compiled with the module added via --add-module. A sample Dockerfile demonstrates building an OpenResty image with the patched Nginx.

FROM xxx.com/openresty
ADD ./openresty-1.11.2.5.tar.gz /opt
RUN set -e && cd /opt/openresty-1.11.2.5/bundle/nginx-1.11.2 && \
    patch -p0 < /opt/nginx_upstream_check_module-master/check_1.11.1+.patch
RUN set -e && cd /opt/openresty-1.11.2.5/ && \
    ./configure --with-luajit --with-http_image_filter_module \
    --with-http_realip_module --add-module=/opt/nginx_upstream_check_module-master/ \
    --with-http_sub_module && make && make install

The module also provides a status page (HTML, JSON, CSV) that can be queried to see real‑time node health.

Conclusion

All three methods achieve backend health monitoring, but the ngx_http_upstream_check_module offers the most seamless integration with minimal impact on downstream services, making it the preferred choice for production OpenResty deployments.