Upstream Probe#

The module implements active health probes for http_upstream.

Configuration Example# 

server {
    listen ...;

    location @probes {
        ...
        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)#

Added in version 1.2.0: PRO

Syntax

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

Default

—

Context

location

Defines an active health probe for peers within the upstream groups that are specified for proxy_pass, uwsgi_pass, and so on in the same location context with the upstream_probe directive. Subsequently, Angie regularly probes each peer of the upstream group according to the parameters configured here.

A peer's probe is passed if the request to the peer succeeds, considering all parameter settings of the upstream_probe directive and the settings that control how upstreams are used by the directive's location context. This includes the proxy_next_upstream and uwsgi_next_upstream directives, etc.; also, proxy_set_header and so on.

To make use of 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 added to the argument for 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.
By default — GET.

test

The condition for the probe, defined as a string with variables. If variable substitution yields "" or "0", the probe is not passed.

essential

If set, the initial state of the peer is being checked, so the peer doesn't receive client requests until the probe is passed.

persistent

Setting this parameter requires enabling essential first; persistent peers that were deemed healthy prior to a configuration reload start receiving requests without being required to pass this probe first.

fails

Number of subsequent failed probes that renders the peer unhealthy.
By default — 1.

passes

Number of subsequent passed probes that renders the peer unhealthy.
By default — 1.

max_body

Maximum amount of memory for the response body.
By default — 256k.

mode

Probe mode, depending on the peers' health:

  • always — peers are probed regardless of their state;

  • idle — probes affect unhealthy peers and peers where interval has elapsed since the last client request.

  • onfail — only unhealthy peers 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 @probes {
        ...
        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 peer won't receive client requests until it passes all essential probes configured for it, skipping persistent ones if the configuration was reloaded and the peer was deemed healthy prior to that. If there are no such probes, the peer is considered healthy.

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

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

Built-in Variables#

The http_upstream module supports the following built-in variables:

$upstream_probe (PRO)#

Name of the currently active upstream_probe.

$upstream_probe_body (PRO)#

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

On this page