diff xml/en/docs/http/ngx_http_upstream_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 a58b35cc0823
children 5c55b7054b58
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_upstream_module.xml
+++ b/xml/en/docs/http/ngx_http_upstream_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_upstream_module"
         link="/en/docs/http/ngx_http_upstream_module.html"
         lang="en"
-        rev="59">
+        rev="60">
 
 <section id="summary">
 
@@ -49,7 +49,8 @@ server {
 </para>
 
 <para>
-Dynamically configurable group,
+Dynamically configurable group with
+periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is
 available as part of our
 <commercial_version>commercial subscription</commercial_version>:
 <example>
@@ -321,7 +322,7 @@ the rest of SRV records are ignored.
 <tag-desc>
 sets the <value>time</value> during which the server will recover its weight
 from zero to a nominal value, when unhealthy server becomes
-<link id="health_check">healthy</link>,
+<link doc="ngx_http_upstream_hc_module.xml" id="health_check">healthy</link>,
 or when the server becomes available after a period of time
 it was considered <link id="fail_timeout">unavailable</link>.
 Default value is zero, i.e. slow start is disabled.
@@ -741,302 +742,6 @@ This directive is available as part of o
 </directive>
 
 
-<directive name="health_check">
-<syntax>[<value>parameters</value>]</syntax>
-<default/>
-<context>location</context>
-
-<para>
-Enables periodic health checks of the servers in a
-<link 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 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 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>
-
-<para>
-<note>
-This directive is available as part of our
-<commercial_version>commercial subscription</commercial_version>.
-</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>
-
-<para>
-<note>
-This directive is available as part of our
-<commercial_version>commercial subscription</commercial_version>.
-</note>
-</para>
-
-</directive>
-
-
 <directive name="queue">
 <syntax>
 <value>number</value>