Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 1945:88477c5d2751
Moved "health_check" and "match" to ngx_http_upstream_hc_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 30 Mar 2017 21:26:44 +0300 |
parents | xml/en/docs/http/ngx_http_upstream_module.xml@a58b35cc0823 |
children | 37df1535ea91 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_upstream_hc_module.xml Thu Mar 30 21:26:44 2017 +0300 @@ -0,0 +1,348 @@ +<?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="1"> + +<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. +</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> +</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> + +<para> +For example, +<example> +location / { + proxy_pass http://backend; + health_check; +} +</example> +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. +Client requests are not passed to unhealthy servers +and servers in the “checking” state. +</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. +For example: +<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, content type “<literal>text/html</literal>”, +and contain “<literal>Welcome to nginx!</literal>” in the body. +</para> + +<para> +The server group must reside in the +<link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>. +</para> + +<para> +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. +</para> + +<para> +<note> +Please note that most of the variables will have empty values +when used with health checks. +</note> +</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>