Upstream Probe

The module implements active health probes for Upstream.

Configuration Example

server {
    listen ...;

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

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}

Directives

upstream_probe (PRO)

Syntax	upstream_probe name [uri=address] [port=number] [interval=time] [method=method] [test=condition] [essential [persistent]] [fails=number] [passes=number] [max_body=size] [mode=always | idle | onfail];
Default	—
Context	location

Defines an active health probe for servers within the upstream groups that are specified in proxy_pass, uwsgi_pass, and similar directives in the same location context as the upstream_probe directive. Angie regularly performs requests according to the specified parameters to each server in the upstream group.

A server passes the probe if the request to it succeeds, considering all parameter settings of the upstream_probe directive and all parameters that control how upstreams are used by the location context where it is defined. This includes the proxy_next_upstream and uwsgi_next_upstream directives, etc., as well as proxy_set_header and so on.

To use the probes, the upstream must have a shared memory zone (zone). One upstream may be configured with several probes.

The following parameters are accepted:

name	Mandatory name of the probe.
uri	Request URI to be appended to the argument of proxy_pass, uwsgi_pass, etc. By default — /.
port	Alternative port number for the probe request.
interval	Interval between probes. By default — 5s.
method	HTTP method of the probe request. By default — GET.
test	The condition to be checked during the request; defined as a string with variables. If variable substitution yields "" or "0", the probe fails.
essential	If set, the initial state of the server is subject to verification and client requests are not forwarded to it until the probe is passed.
persistent	Setting this parameter requires enabling essential first; persistent servers that were working prior to a configuration reload start receiving requests without being required to pass this probe first.
fails	Number of consecutive failed requests that renders the server unhealthy. By default — 1.
passes	Number of consecutive successful requests that renders the server healthy. By default — 1.
max_body	Maximum amount of memory for the response body. By default — 256k.
mode	Probe mode, depending on the servers' health: always — servers are probed regardless of their state; idle — probes affect unhealthy servers and servers where interval has elapsed since the last client request. onfail — only unhealthy servers are probed. By default — always.

Example:

upstream backend {
    zone backend 1m;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_status $good {
    200     "1";
}

server {
    listen ...;

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

        upstream_probe backend_probe
            uri=/probe
            port=10004
            interval=5s
            test=$good
            essential
            persistent
            fails=3
            passes=3
            max_body=10m
            mode=idle;
    }
}

Details of probe operation:

• Initially, the server won't receive client requests until it passes all essential probes configured for it (skipping persistent ones if the configuration was reloaded and the server was deemed healthy prior to that). If there are no such probes, the server is considered healthy.

• The server is considered unhealthy and won't receive client requests if any of the probes configured for it hits its fails threshold or the server itself reaches the max_fails threshold.

• For an unhealthy server to be considered healthy again, all probes configured for it must reach their respective passes thresholds; after that, the max_fails threshold is considered.

Built-in Variables

The http_upstream_probe module supports the following built-in variables:

$upstream_probe (PRO)

Name of the currently active upstream_probe.

$upstream_probe_body (PRO)

Server response body received during an upstream_probe; its size is limited by max_body.