Mercurial > hg > nginx-site
view xml/en/docs/stream/ngx_stream_upstream_hc_module.xml @ 2313:35b02ed44e4a
Removed example from JSON.stringify in njs reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 25 Dec 2018 16:42:05 +0300 |
parents | f069d4b7a8df |
children | 9dd8c203a54a |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_stream_upstream_hc_module" link="/en/docs/stream/ngx_stream_upstream_hc_module.html" lang="en" rev="5"> <section id="summary"> <para> The <literal>ngx_stream_upstream_hc_module</literal> module (1.9.0) allows enabling periodic health checks of the servers in a <link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. The server group must reside in the <link doc="ngx_stream_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 connections are not passed to unhealthy servers and servers in the “checking” state. </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 tcp { zone upstream_tcp 64k; server backend1.example.com:12345 weight=5; server backend2.example.com:12345 fail_timeout=5s slow_start=30s; server 192.0.2.1:12345 max_fails=3; server backup1.example.com:12345 backup; server backup2.example.com:12345 backup; } server { listen 12346; proxy_pass tcp; health_check; } </example> With this configuration, nginx will check the ability to establish a TCP connection to each server in the <literal>tcp</literal> group every five seconds. When a connection to the server cannot be established, the health check will fail, and the server will be considered unhealthy. </para> <para> Health checks can be configured for the UDP protocol: <example> upstream dns_upstream { zone dns_zone 64k; server dns1.example.com:53; server dns2.example.com:53; server dns3.example.com:53; } server { listen 53 udp; proxy_pass dns_upstream; health_check udp; } </example> In this case, the absence of ICMP “<literal>Destination Unreachable</literal>” message is expected in reply to the sent string “<literal>nginx health check</literal>”. </para> <para> Health checks can also be configured to test data obtained from the server. 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. </para> </section> <section id="directives" name="Directives"> <directive name="health_check"> <syntax>[<value>parameters</value>]</syntax> <default/> <context>server</context> <para> Enables periodic health checks of the servers in a <link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>. </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_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 connections 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 successful connection should pass in order for a health check to pass. By default, for TCP, only the ability to establish a TCP connection with the server is checked. For <link id="health_check_udp">UDP</link>, the absence of ICMP “<literal>Destination Unreachable</literal>” message is expected in reply to the sent string “<literal>nginx health check</literal>”. <note> Prior to version 1.11.7, by default, UDP health check required a <link id="hc_match">match</link> block with the <link id="match_send">send</link> and <link id="match_expect">expect</link> parameters. </note> </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_stream_upstream_module.xml" id="server"/> port. </tag-desc> <tag-name id="health_check_udp"> <literal>udp</literal> </tag-name> <tag-desc> specifies that the <literal>UDP</literal> protocol should be used for health checks instead of the default <literal>TCP</literal> protocol (1.9.13). </tag-desc> </list> </para> </directive> <directive name="health_check_timeout"> <syntax><value>timeout</value></syntax> <default>5s</default> <context>stream</context> <context>server</context> <para> Overrides the <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> value for health checks. </para> </directive> <directive name="match"> <syntax block="yes"><value>name</value> </syntax> <default/> <context>stream</context> <para> Defines the named test set used to verify server responses to health checks. </para> <para> The following parameters can be configured: <list type="tag"> <tag-name id="match_send"> <literal>send</literal> <value>string</value>; </tag-name> <tag-desc> sends a <value>string</value> to the server; </tag-desc> <tag-name id="match_expect"> <literal>expect</literal> <value>string</value> | <literal>~</literal> <value>regex</value>; </tag-name> <tag-desc> a literal string (1.9.12) or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding “<literal>~*</literal>” modifier (for case-insensitive matching), or the “<literal>~</literal>” modifier (for case-sensitive matching). </tag-desc> </list> Both <literal>send</literal> and <literal>expect</literal> parameters can contain hexadecimal literals with the prefix “<literal>\x</literal>” followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12). </para> <para> Health check is passed if: <list type="bullet"> <listitem> the TCP connection was successfully established; </listitem> <listitem> the <value>string</value> from the <literal>send</literal> parameter, if specified, was sent; </listitem> <listitem> the data obtained from the server matched the string or regular expression from the <literal>expect</literal> parameter, if specified; </listitem> <listitem> the time elapsed does not exceed the value specified in the <link id="health_check_timeout"/> directive. </listitem> </list> </para> <para> Example: <example> upstream backend { zone upstream_backend 10m; server 127.0.0.1:12345; } match http { send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; expect ~ "200 OK"; } server { listen 12346; proxy_pass backend; health_check match=http; } </example> </para> <para> <note> Only the first <link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/> bytes of data obtained from the server are examined. </note> </para> </directive> </section> </module>