health_check

Enables periodic health checks of the servers in a group referenced in the surrounding location.

The following optional parameters are supported:

interval=time

sets the interval between two consecutive health checks, by default, 5 seconds.

jitter=time

sets the time within which each health check will be randomly delayed, by default, there is no delay.

fails=number

sets the number of consecutive failed health checks of a particular server after which this server will be considered unhealthy, by default, 1.

passes=number

sets the number of consecutive passed health checks of a particular server after which the server will be considered healthy, by default, 1.

uri=uri

defines the URI used in health check requests, by default, “/”.

match=name

specifies the match block configuring the tests that a response should pass in order for a health check to pass. By default, the response should have status code 2xx or 3xx.

port=number

defines the port used when connecting to a server to perform a health check (1.9.7). By default, equals the server port.

For example,

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

will send “/” requests to each server in the backend group every five seconds. If any communication error or timeout occurs, or a proxied server responds with the status code other than 2xx or 3xx, the health check will fail, and the server will be considered unhealthy. Client requests are not passed to unhealthy servers.

Health checks can be configured to test the status code of a response, presence of certain header fields and their values, and the body contents. Tests are configured separately using the match directive and referenced in the match parameter. For example:

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

This configuration shows that in order for a health check to pass, the response to a health check request should succeed, have status 200, content type “text/html”, and contain “Welcome to nginx!” in the body.

The server group must reside in the shared memory.

If several health checks are defined for the same group of servers, a single failure of any check will make the corresponding server be considered unhealthy.

Please note that most of the variables will have empty values when used with health checks.

This directive is available as part of our commercial subscription.