Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 1946:37df1535ea91
Moved info from http "health_check" and "match" to intro.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 30 Mar 2017 21:26:44 +0300 |
parents | 88477c5d2751 |
children | 8f9c685dfabd |
line wrap: on
line source
<?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="2"> <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="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="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="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="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). If the parameter is not specified, the server will be initially considered healthy. </tag-desc> <tag-name id="hc_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> </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> </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> </para> </directive> </section> </module>