Health Checks

Passive Health Checks (Open Source)

Nginx OSS uses passive health checking based on request failures.

upstream backend {
    server 10.0.0.1:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.3:8080 backup;
}

Parameters

Proxy Error Handling

upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

server {
    location / {
        proxy_pass http://backend;

        # Retry on these errors
        proxy_next_upstream error timeout http_500 http_502 http_503;

        # Limit retry attempts
        proxy_next_upstream_tries 3;

        # Timeout for retries
        proxy_next_upstream_timeout 10s;
    }
}

Custom Health Check Endpoint

Application Side

// Express.js health check
app.get('/health', (req, res) => {
    // Check database, cache, etc.
    const healthy = checkServices();
    if (healthy) {
        res.status(200).json({ status: 'ok' });
    } else {
        res.status(503).json({ status: 'unhealthy' });
    }
});

Nginx Configuration

upstream backend {
    server 10.0.0.1:8080 max_fails=2 fail_timeout=10s;
    server 10.0.0.2:8080 max_fails=2 fail_timeout=10s;
}

server {
    # Internal health check endpoint
    location /health-check {
        internal;
        proxy_pass http://backend/health;
        proxy_connect_timeout 1s;
        proxy_read_timeout 1s;
    }

    location / {
        proxy_pass http://backend;
    }
}

External Health Check Script

#!/bin/bash
# /usr/local/bin/nginx-health-check.sh

SERVERS="10.0.0.1:8080 10.0.0.2:8080"
HEALTH_PATH="/health"

for server in $SERVERS; do
    response=$(curl -s -o /dev/null -w "%{http_code}" \
        --connect-timeout 2 \
        "http://$server$HEALTH_PATH")

    if [ "$response" != "200" ]; then
        echo "$(date): $server is unhealthy (HTTP $response)"
        # Could trigger nginx reload with modified upstream
    fi
done

Graceful Degradation

upstream primary {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

upstream fallback {
    server 10.0.0.10:8080;
}

server {
    location / {
        proxy_pass http://primary;
        proxy_intercept_errors on;

        # Fall back on errors
        error_page 502 503 504 = @fallback;
    }

    location @fallback {
        proxy_pass http://fallback;
    }
}

Health Check with Keepalive

upstream backend {
    zone backend 64k;

    server 10.0.0.1:8080 max_fails=2 fail_timeout=10s;
    server 10.0.0.2:8080 max_fails=2 fail_timeout=10s;

    keepalive 32;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Health check via regular traffic
        proxy_connect_timeout 3s;
        proxy_read_timeout 10s;
    }
}

Monitoring Upstream Status

# Enable stub status module
server {
    listen 127.0.0.1:8080;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

# Check status
curl http://127.0.0.1:8080/nginx_status