NginxHow-ToBeginner · 4 min read

How to Add Health Check in Nginx: Simple Guide

To add a health check in nginx, use the ngx_http_healthcheck_module or configure a simple location block that probes backend servers with proxy_pass and proxy_next_upstream. This setup lets Nginx detect unhealthy servers and avoid sending traffic to them.

📐

Syntax

The basic syntax for adding a health check in Nginx involves defining an upstream block with backend servers and configuring health check parameters. You then use a location block to proxy requests and enable health checks.

upstream: Defines backend servers.
server: Lists each backend server with optional parameters.
health_check: Enables active health checks (requires ngx_http_healthcheck_module).
proxy_pass: Forwards client requests to upstream servers.
proxy_next_upstream: Controls failover behavior.

nginx

upstream backend {
    server backend1.example.com;
    server backend2.example.com;
    health_check;
}

server {
    listen 80;

    location / {
        proxy_pass http://backend;
        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
    }
}

💻

Example

This example shows how to configure Nginx with active health checks using the health_check directive in the upstream block. It probes backend servers and skips unhealthy ones automatically.

nginx

upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    health_check interval=5 fails=3 passes=2;
}

server {
    listen 80;

    location / {
        proxy_pass http://backend;
        proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
    }
}

Output

Nginx starts and probes backend servers every 5 seconds. If a server fails 3 consecutive checks, it is marked unhealthy. Once it passes 2 checks, it is marked healthy again. Requests are only sent to healthy servers.

⚠️

Common Pitfalls

Not enabling the ngx_http_healthcheck_module which is required for health_check directive.
Forgetting to reload or restart Nginx after configuration changes.
Using proxy_next_upstream incorrectly, causing requests to fail without failover.
Not setting proper intervals and thresholds, leading to false positives or negatives.
Assuming passive health checks alone detect all failures; active checks are more reliable.

nginx

## Wrong: Missing health_check directive
upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

## Right: Add health_check directive
upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    health_check interval=5 fails=3 passes=2;
}

📊

Quick Reference

Directive	Description	Example
upstream	Defines backend servers group	upstream backend { server 127.0.0.1:8080; }
health_check	Enables active health checks (ngx_http_healthcheck_module)	health_check interval=5 fails=3 passes=2;
proxy_pass	Forwards requests to upstream	proxy_pass http://backend;
proxy_next_upstream	Controls failover on errors	proxy_next_upstream error timeout http_500;

✅

Key Takeaways

Use the ngx_http_healthcheck_module to enable active health checks in Nginx upstream blocks.

Configure health_check with proper intervals and failure thresholds to detect unhealthy servers accurately.

Use proxy_next_upstream to control request failover when a backend server is down.

Always reload Nginx after changing health check configurations to apply changes.

Passive health checks alone may not be enough; active health checks improve reliability.