<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_upstream_hc_module"
        link="/en/docs/http/ngx_http_upstream_hc_module.html"
        lang="en"
        rev="5">

<section id="summary">

<para>
The <literal>ngx_http_upstream_hc_module</literal> module
allows enabling periodic health checks of the servers in a
<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
referenced in the surrounding location.
The server group must reside in the
<link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>.
</para>

<para>
If a health check fails,
the server will be considered unhealthy.
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.
Client requests are not passed to unhealthy servers
and servers in the “checking” state.
</para>

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

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;

    server backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}
</example>
With this configuration, nginx will send “<literal>/</literal>” requests to each
server in the <literal>backend</literal> 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.
</para>

<para>
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 <link id="match"/> directive
and referenced in the <literal>match</literal> parameter
of the  <link id="health_check"/> directive:
<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!";
    }
}
</example>
This configuration shows that in order for a health check to pass, the response
to a health check request should succeed, have status 200,
and contain “<literal>Welcome to nginx!</literal>” in the body.
</para>

</section>


<section id="directives" name="Directives">

<directive name="health_check">
<syntax>[<value>parameters</value>]</syntax>
<default/>
<context>location</context>

<para>
Enables periodic health checks of the servers in a
<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
referenced in the surrounding location.
</para>

<para>
The following optional parameters are supported:
<list type="tag">

<tag-name id="health_check_interval">
<literal>interval</literal>=<value>time</value>
</tag-name>
<tag-desc>
sets the interval between two consecutive health checks,
by default, 5 seconds.
</tag-desc>

<tag-name id="health_check_jitter">
<literal>jitter</literal>=<value>time</value>
</tag-name>
<tag-desc>
sets the time within which
each health check will be randomly delayed,
by default, there is no delay.
</tag-desc>

<tag-name id="health_check_fails">
<literal>fails</literal>=<value>number</value>
</tag-name>
<tag-desc>
sets the number of consecutive failed health checks of a particular server
after which this server will be considered unhealthy,
by default, 1.
</tag-desc>

<tag-name id="health_check_passes">
<literal>passes</literal>=<value>number</value>
</tag-name>
<tag-desc>
sets the number of consecutive passed health checks of a particular server
after which the server will be considered healthy,
by default, 1.
</tag-desc>

<tag-name id="health_check_uri">
<literal>uri</literal>=<value>uri</value>
</tag-name>
<tag-desc>
defines the URI used in health check requests,
by default, “<literal>/</literal>”.
</tag-desc>

<tag-name id="health_check_mandatory">
<literal>mandatory</literal>
</tag-name>
<tag-desc>
sets the initial “checking” state for a server
until the first health check is completed (1.11.7).
Client requests are not passed to servers in the “checking” state.
If the parameter is not specified,
the server will be initially considered healthy.
</tag-desc>

<tag-name id="health_check_match">
<literal>match</literal>=<value>name</value>
</tag-name>
<tag-desc>
specifies the <literal>match</literal> 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.
</tag-desc>

<tag-name id="health_check_port">
<literal>port</literal>=<value>number</value>
</tag-name>
<tag-desc>
defines the port used when connecting to a server
to perform a health check (1.9.7).
By default, equals the
<link doc="ngx_http_upstream_module.xml" id="server"/> port.
</tag-desc>

<tag-name id="health_check_grpc">
<literal>type</literal>=<literal>grpc</literal>
[<literal>grpc_service</literal>=<value>name</value>]
[<literal>grpc_status</literal>=<value>code</value>]
</tag-name>
<tag-desc>
enables periodic
<link url="https://github.com/grpc/grpc/blob/master/doc/health-checking.md#grpc-health-checking-protocol">health
checks</link> of a gRPC server
or a particular gRPC service specified with the optional
<literal>grpc_service</literal> parameter (1.19.5).
If the server does not support the gRPC Health Checking Protocol,
the optional <literal>grpc_status</literal> parameter can be used
to specify non-zero gRPC
<link url="https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc">status</link>
(for example,
status code “<literal>12</literal>” / “<literal>UNIMPLEMENTED</literal>”)
that will be treated as healthy:
<example>
health_check mandatory type=grpc grpc_status=12;
</example>
The <literal>type</literal>=<literal>grpc</literal> parameter
must be specified after all other directive parameters,
<literal>grpc_service</literal> and <literal>grpc_status</literal>
must follow <literal>type</literal>=<literal>grpc</literal>.
The parameter is not compatible with
<link id="health_check_uri"><literal>uri</literal></link> or
<link id="health_check_match"><literal>match</literal></link> parameters.
</tag-desc>

</list>
</para>

</directive>


<directive name="match">
<syntax block="yes"><value>name</value></syntax>
<default/>
<context>http</context>

<para>
Defines the named test set used to verify responses to health check requests.
</para>

<para>
The following items can be tested in a response:
<list type="tag">

<tag-name><literal>status 200;</literal></tag-name>
<tag-desc>status is 200</tag-desc>

<tag-name><literal>status ! 500;</literal></tag-name>
<tag-desc>status is not 500</tag-desc>

<tag-name><literal>status 200 204;</literal></tag-name>
<tag-desc>status is 200 or 204</tag-desc>

<tag-name><literal>status ! 301 302;</literal></tag-name>
<tag-desc>status is neither 301 nor 302</tag-desc>

<tag-name><literal>status 200-399;</literal></tag-name>
<tag-desc>status is in the range from 200 to 399</tag-desc>

<tag-name><literal>status ! 400-599;</literal></tag-name>
<tag-desc>status is not in the range from 400 to 599</tag-desc>

<tag-name><literal>status 301-303 307;</literal></tag-name>
<tag-desc>status is either 301, 302, 303, or 307</tag-desc>

</list>

<list type="tag">

<tag-name><literal>header Content-Type = text/html;</literal></tag-name>
<tag-desc>
header contains <header>Content-Type</header>
with value <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Content-Type != text/html;</literal></tag-name>
<tag-desc>
header contains <header>Content-Type</header>
with value other than <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Connection ~ close;</literal></tag-name>
<tag-desc>
header contains <header>Connection</header>
with value matching regular expression <literal>close</literal>
</tag-desc>

<tag-name><literal>header Connection !~ close;</literal></tag-name>
<tag-desc>
header contains <header>Connection</header>
with value not matching regular expression <literal>close</literal>
</tag-desc>

<tag-name><literal>header Host;</literal></tag-name>
<tag-desc>header contains <header>Host</header></tag-desc>

<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
<tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>

</list>

<list type="tag">

<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
body matches regular expression “<literal>Welcome to nginx!</literal>”
</tag-desc>

<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
body does not match regular expression “<literal>Welcome to nginx!</literal>”
</tag-desc>

</list>

<list type="tag">

<tag-name id="match_require"><literal>require</literal>
                             <value>$variable</value>
                             <literal>...;</literal></tag-name>
<tag-desc>
all specified variables are not empty and not equal to “0” (1.15.9).
</tag-desc>

</list>
</para>

<para>
If several tests are specified,
the response matches only if it matches all tests.
<note>
Only the first 256k of the response body are examined.
</note>
</para>

<para>
Examples:
<example>
# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}
</example>

<example>
# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}
</example>

<example>
# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}
</example>

<example>
# status is 200 or 204
map $upstream_status $good_status {
    200 1;
    204 1;
}

match server_ok {
    require $good_status;
}
</example>

</para>

</directive>

</section>

</module>